Install Pilot and Connect Linear via Localtonet

What you are building and what was verified

This workflow has three independent layers. Pilot is the automation application. Linear is the event source and ticket provider. Localtonet supplies public network reachability to an HTTP service running on or reachable from the connected client device.

The Localtonet client establishes an outbound connection to one of our relay servers. An HTTP tunnel then provides a public HTTPS address that forwards requests to the configured local IP address and port. This arrangement does not require inbound router port forwarding, firewall changes, a VPN, or a public IP address. The endpoint remains available only while Pilot is listening, the selected Localtonet client is connected, and the tunnel is running.

Network reachability is not webhook authorization. Localtonet routes an incoming HTTP request to the selected local target, but the receiving Pilot integration must still validate the exact path, signature, payload, event type, and any provider or repository permissions. A successful tunnel cannot correct an incorrect Pilot configuration, missing Linear credentials, an invalid signature, or insufficient repository access.

This distinction also corrects older onboarding terminology. The repository README still shows pilot init in its quick start, while the current Pilot documentation homepage promotes pilot setup. For the v2.270.0 documentation workflow covered here, use pilot setup. Treat pilot init as an alternative or older repository workflow unless the documentation bundled with your installed build explicitly instructs you to use it.

Earlier material also described 127.0.0.1:9090 as a universal default and referred to a --no-gateway option. Neither claim is established by the supplied v2.270.0 evidence. This revision does not rely on either value. Use the listener address printed by your actual Pilot process or shown by its release-specific configuration, then enter that verified address in Localtonet.

Pilot, repository, and Linear prerequisites

Prepare the complete application chain before creating a public tunnel. Pilot requires Claude Code CLI 2.1.17 or later according to its repository. Pilot’s current documentation says it can use an existing Claude subscription when Claude Code is already authenticated, or an Anthropic API key through a supported configuration. An OpenAI API key is optional and is associated with voice transcription rather than the basic ticket workflow.

Go 1.22 or later is required only when installing with Go or building from source. It is not listed as a requirement for every packaged installation. You also need a Git repository host supported by the Pilot workflow, credentials with access to the intended repositories, and a Linear account authorized to configure the relevant workspace integration.

Application prerequisites

• A supported machine on which Pilot can remain running.
• Claude Code CLI 2.1.17 or later, installed and authenticated.
• A Pilot v2.270.0 installation or another explicitly identified version.
• Access to the repository and its required build, test, and lint tools.
• A clean local port on which the Pilot HTTP listener can start.

Provider and repository prerequisites

• A Linear workspace and permission to create or manage a webhook.
• The Linear API credential required by the Pilot adapter, if the installed adapter uses the API for task synchronization.
• The Linear webhook signing secret created or displayed during webhook configuration.
• A repository-provider token, such as the GitHub or GitLab token required by the selected repository workflow.
• Repository permissions limited to the projects Pilot is expected to modify.

Localtonet prerequisites

• A Localtonet account and a client installation for the relevant operating system.
• A connected device token for the machine that can reach Pilot.
• An available Localtonet relay server selected from the current dashboard.
• The verified local IP address and port on which Pilot is listening.

Install and configure Pilot v2.270.0

Pilot currently presents more than one installation path. The documentation homepage promotes an installation script, while the repository continues to list Homebrew, Go, source, and desktop options. These are alternatives. Choose one path and avoid mixing binaries, configuration directories, or desktop and command-line processes unless Pilot’s version-specific instructions explicitly require that arrangement.

Current documentation installation path

The current Pilot documentation homepage promotes this Unix-like shell command:

curl -fsSL https://raw.githubusercontent.com/qf-studio/pilot/main/install.sh | bash

Piping a remote script directly to a shell is convenient but grants that script the permissions of your current account. In a controlled environment, download and inspect it first or use one of the repository installation alternatives below. Windows users should use the supported Windows installer or desktop release rather than assuming a Bash command applies to PowerShell.

Homebrew alternative

brew tap qf-studio/pilot
brew install pilot

Go alternative

go install github.com/qf-studio/pilot/cmd/pilot@latest

If the shell cannot find pilot afterward, inspect your Go environment and add the actual Go binary directory to your shell’s executable path. Do not assume that every machine uses the same location.

Source-build alternative

git clone https://github.com/qf-studio/pilot
cd pilot
make build
sudo make install-global

Inspect the repository and the installation target before running the privileged final command. If you need an exact release rather than the repository’s current main branch, check out the intended release tag before building.

Run current setup

After installing the current documentation build, start its configuration flow:

pilot setup

Complete the prompts shown by that installed release. Authenticate Claude Code before attempting an automated task. Configure the repository provider required by the destination repository, then configure Linear as the ticket provider using only the fields shown by the v2.270.0 setup flow or its Linear integration page.

The current documentation homepage demonstrates a GitHub repository token with the following environment variable:

export GITHUB_TOKEN="your-token"

Use GITLAB_TOKEN instead when following the corresponding GitLab workflow documented by Pilot. The token value above is intentionally a placeholder. Store real credentials in a protected secret store or process environment appropriate to your deployment rather than a shell-history entry, public repository, screenshot, or shared configuration file.

For version-specific details, use the Pilot installation documentation, the Pilot repository, and the Pilot v2.270.0 release page. Confirm the output of your installed binary before assuming that the latest documentation and an older package behave identically.

Configure Pilot’s Linear adapter and Linear webhook

A complete Linear connection needs four application values: Pilot’s Linear API credential setting, Pilot’s webhook-secret setting, the exact Pilot webhook path, and the event types accepted by the adapter. It also needs a repository-provider credential because receiving a Linear ticket does not itself grant Pilot permission to clone, modify, or push a repository.

Record the adapter contract before startup

Create a private deployment record containing the following values from the installed Pilot release. This record should contain secret references rather than secret values:

Understand Linear signature verification

Linear signs webhook requests with HMAC-SHA256 using the webhook’s signing secret and sends the result in the Linear-Signature header. Verification must be calculated over the unmodified raw HTTP request body. Parsing and re-serializing JSON before computing the digest can change whitespace or field representation and cause a valid request to fail verification.

Pilot’s adapter should perform this verification when its documented signing-secret setting is configured. Confirm that behavior in the selected release before exposure. The verification process should compare the computed digest with the received signature safely, reject a missing or incorrect signature, and avoid starting repository work until validation succeeds. Localtonet forwards the request but does not replace Pilot’s signature check.

Linear includes a webhook timestamp that receivers can use to reject stale deliveries. Follow the current Linear and Pilot guidance for the accepted time window. Do not create a permissive fallback that accepts unsigned requests merely because a timestamp is present.

Create the Linear-side webhook

Perform these actions only after Pilot is configured locally and Localtonet has assigned the public origin:

1. Open the webhook or API settings for the intended Linear workspace using an authorized account.
2. Create a webhook with a descriptive name tied to this Pilot environment.
3. Set its destination to the Localtonet public HTTPS origin followed by Pilot’s confirmed route.
4. Select only the event categories required by the documented Pilot adapter, normally the issue-related scope when Pilot is consuming Linear tickets.
5. Copy the generated signing secret into Pilot’s documented secret setting using protected credential storage.
6. Save the webhook and retain access to Linear’s delivery status for controlled testing.

The destination has this conceptual form:

https://assigned-public-origin.example/PILOT_RELEASE_SPECIFIC_ROUTE

The example is deliberately not a deployable URL. Replace both parts with the actual Localtonet address and exact route reported by Pilot v2.270.0. Do not register only the public origin unless Pilot explicitly documents the root path as its Linear handler.

Consult the Linear webhook documentation for the current workspace configuration, signature, timestamp, event, and delivery behavior. Linear retries unsuccessful webhook deliveries, so the handler must tolerate duplicate delivery of the same logical event. A retry must not create a second branch, duplicate pull request, or repeated destructive action.

Start Pilot and verify the local listener

The current documentation homepage demonstrates startup with GitHub polling and the terminal dashboard:

pilot start --github --dashboard

This command confirms the current dashboard startup pattern, but it does not prove that GitHub polling activates the Linear adapter. Do not substitute it for a Linear-specific activation command unless the installed Pilot help or Linear documentation says both integrations should be started together. Likewise, do not use an unverified --linear flag.

Start Pilot using the exact command generated or documented by the v2.270.0 setup flow for Linear. Keep the foreground logs or dashboard visible during initial validation. The expected evidence at this stage is:

• Pilot starts without a configuration or credential error.
• Claude Code authentication is recognized.
• The selected repository provider is initialized successfully.
• The Linear adapter reports that it is enabled or ready.
• An HTTP listener starts on a specific IP address and port.
• No other process already owns that address.

If Pilot prints a listener such as 127.0.0.1 with a port, record exactly what it prints. A loopback listener can be targeted by Localtonet only when the Localtonet client runs on the same machine. If Pilot listens on another address, confirm that the client device can reach it and that doing so is consistent with your network policy.

First perform a harmless request against a health, status, or root endpoint explicitly documented by the installed release. Do not send a fabricated Linear payload to the webhook route as a health check because malformed or partially valid events can create confusing logs or unintended retries.

If Pilot does not document a harmless HTTP health endpoint, verify the listener with operating-system network tools and Pilot’s own startup status. A listening socket proves that a process owns the address, but it does not prove that the Linear route, signature validation, credentials, or repository mapping are correct.

Protect the automation boundary

Pilot is not a passive website. Depending on its configuration, an accepted event can claim work, create a branch, modify files, run commands and tests, push changes, or open a pull request. Exposing its HTTP listener therefore creates an automation boundary with consequences beyond returning an HTTP response.

• Use a unique Linear webhook secret for this endpoint and environment.
• Store the secret in Pilot’s supported secret mechanism, not in source control.
• Verify signatures over the raw request body before parsing or acting on an event.
• Restrict Linear events to the minimum scope required by Pilot.
• Map only the intended Linear team or project to the intended repository.
• Use repository credentials with the least practical permissions.
• Keep branch protection, CI checks, and human pull-request review where appropriate.
• Design processing to be idempotent because retries and duplicate deliveries can occur.

Rotate a webhook secret safely

Treat rotation as a coordinated change. Stop or pause the public tunnel if the Pilot adapter cannot accept both the old and new secret during a transition. Create or retrieve the new Linear secret, update Pilot’s protected configuration, restart or reload Pilot as documented, and verify that the adapter is ready before resuming the tunnel. Send a controlled event and confirm that the new signature is accepted. Remove the old secret after the successful test.

If a secret may have been disclosed, stop the tunnel immediately, revoke or rotate the secret, inspect Linear delivery history and Pilot logs, and review repository activity for unexpected branches, commits, or pull requests. Rotating only the Localtonet address does not invalidate a compromised Linear signing secret.

Create and start the Localtonet HTTP tunnel

Create the tunnel only after Pilot is healthy locally. The Localtonet client must run on the Pilot machine or another device that can reach Pilot’s verified listener. If Pilot listens on 127.0.0.1, run both processes on the same machine because loopback always refers to the device making the connection.

The current product workflow and available options are documented in the Localtonet HTTP tunnel documentation.

Verify the public route and run a controlled Linear delivery

Verification should progress from harmless network checks to one bounded application event. Do not begin with a production ticket that can modify a sensitive repository.

1. Check the public HTTP origin harmlessly

Request only the harmless health, status, or root endpoint already verified locally. Append the same documented path to the Localtonet public origin. Compare the public response with the local response. An HTTP response from Pilot, including a deliberate authorization or method response, demonstrates more than a DNS lookup because it confirms that the request traversed the tunnel to the application.

Do not treat an arbitrary 404 as proof that the Linear route is correct. It may prove that an HTTP server responded, but it can also indicate that the path was forwarded to the wrong application or that Pilot’s adapter is disabled.

2. Register the exact Linear destination

Combine the assigned public origin with Pilot’s confirmed v2.270.0 Linear route. Enter that full URL in Linear, select only the required issue-related event scope documented by Pilot, and configure the same signing secret on both sides.

3. Generate one bounded event

Use a dedicated test team, project, or repository where possible. Create or update one clearly labeled test issue in the exact way Pilot documents as its trigger. Avoid a broad project operation that emits many events. Keep Pilot’s dashboard, process logs, Linear delivery status, and repository activity visible.

4. Confirm every layer

• Linear shows a delivery attempt to the expected full URL.
• The delivery receives the success status expected by the Pilot adapter.
• Pilot logs show the expected route and event type.
• Pilot accepts the signature rather than bypassing validation.
• The event maps to the intended team, project, and repository.
• Exactly one task or work item is created or claimed.
• Repository activity is limited to the expected branch or pull-request workflow.

5. Test rejection safely

Where Pilot provides a documented diagnostic method, confirm that an invalid signature or unsupported event is rejected before any repository action occurs. Do not disable signature validation or send fabricated requests to a production automation endpoint. Linear’s own controlled delivery and Pilot’s documented diagnostics are safer than hand-built payloads whose schema may not match the installed release.

Duplicate delivery must not create duplicate work. If the same Linear event is retried, Pilot should use its documented event or task identity handling to recognize previously processed work. Confirm the actual behavior in a test environment before enabling broad event scope.

Routine operation, shutdown, and rollback

A webhook integration is a running service rather than a one-time configuration. Monitor all three components: Pilot, the connected Localtonet client, and the HTTP tunnel. Also watch Linear’s delivery status and repository activity for repeated failures or unexpected automation.

Normal operating checks

• Keep Pilot on an explicitly managed version and review release notes before upgrading.
• Confirm Claude Code and provider credentials remain valid.
• Keep the Localtonet client connected on the selected device.
• Confirm the tunnel is running after maintenance or a restart.
• Review rejected signatures and repeated deliveries without logging secret values.
• Watch for duplicate tasks, branches, or pull requests.
• Audit repository permissions when teams or projects change.

Planned shutdown

Disable or pause the Linear webhook first when the provider workflow permits it. Then stop the Localtonet tunnel so the public route is no longer available. Stop Pilot after active work has reached a safe state. Stopping the tunnel is operationally separate from creating it and does not delete the tunnel configuration.

Delete the Localtonet tunnel only when the endpoint is permanently retired. Revoke the Linear signing secret and unused provider credentials, then remove stale Pilot configuration according to the release documentation.

Emergency rollback

1. Stop the Localtonet tunnel to remove public reachability.
2. Disable the Linear webhook to stop new deliveries and retries where supported.
3. Stop Pilot if it is processing an unsafe or incorrectly mapped task.
4. Revoke or rotate exposed Linear and repository credentials.
5. Inspect Pilot logs, Linear delivery history, and repository activity.
6. Correct the route, event scope, signature configuration, or repository mapping locally.
7. Repeat local and controlled public verification before restoring service.

Troubleshooting by layer

Installation and PATH problems

Do not repeatedly reinstall Pilot using several methods. First determine whether Homebrew, the installation script, Go, a source build, or the desktop package installed the active binary. Multiple copies can make setup appear inconsistent because one shell may run a different version from another. Confirm the binary resolved by your shell and compare its version with the intended release.

Disconnected Localtonet client or stopped tunnel

A saved tunnel is not necessarily running. Check both the selected client’s connection state and the tunnel state. If the client is disconnected, confirm that the Localtonet application is still running on the expected device. If the client is connected but the tunnel is stopped, start the tunnel separately.

Wrong route versus wrong target

Test the documented harmless public endpoint first. If it fails, investigate the tunnel target. If it succeeds but Linear’s route returns 404, investigate the appended Pilot path. If the path responds but Pilot rejects the request, investigate signature, timestamp, event scope, and adapter configuration.

Provider permissions

Separate Linear permissions from repository permissions. A valid Linear credential does not grant GitHub or GitLab access, and a repository token does not authorize Linear API operations. Check each provider independently and preserve least privilege while troubleshooting.

Frequently asked questions