Run Pilot locally, verify its HTTP gateway, and prepare a controlled endpoint for Linear webhooks
Pilot is a self-hosted development automation daemon that can process tickets, modify repositories, run quality gates, and open pull requests. This guide starts with Pilot installation, initialization, startup, and local gateway verification before introducing remote access. Once the gateway is working on the local machine, we will configure a Localtonet HTTP tunnel so an external service such as Linear can reach it. Because Pilot can act on source repositories, the guide also explains why webhook authentication, least privilege, and careful endpoint validation are essential.
What you are building
The completed setup has two distinct parts. First, Pilot runs as a self-hosted daemon on a machine that can access the repositories and development tools it needs. Its documented default HTTP gateway listens on 127.0.0.1:9090. Binding to the loopback address keeps the gateway local to that machine, which is useful during installation and verification but prevents Linear from delivering webhooks directly over the public internet.
Second, the Localtonet client runs on the same machine, or on another device that can reach the Pilot gateway. The client establishes an outbound connection to one of our relay servers. An HTTP tunnel then maps a public HTTPS address to the local Pilot address and port. This does not require inbound router port forwarding, firewall changes, VPN setup, or a public IP address.
The public address is only the network route. Pilot still determines which webhook path, request format, and integration settings are valid. The available evidence confirms that Pilot supports Linear webhooks and task synchronization, but it does not establish a universal Linear webhook path or authentication behavior. Use the current Pilot Linear integration documentation or the configuration shown by your installed Pilot version for those values. Do not assume that the public tunnel root is itself the webhook destination.
Pilot prerequisites and installation choices
Pilot documents Claude Code CLI 2.1.17 or later as a requirement. An OpenAI API key is optional and is used for voice transcription rather than the core installation flow. Go 1.22 or later is required only when building Pilot from source or using the Go installation route. Before starting the daemon, also confirm that the machine has access to the repositories and ticket provider that you intend to configure.
Homebrew is the recommended command-line installation method in the Pilot README. Go installation, source compilation, and desktop release packages are also documented. Choose one method rather than mixing files from several methods.
| Installation method | Best suited to | Important requirement |
|---|---|---|
| Homebrew | A concise command-line installation using Pilot's documented tap | A working Homebrew installation |
| Go install | Users who already manage Go-installed command-line tools | Go 1.22 or later and a correctly configured Go binary path |
| Build from source | Developers who need to inspect or compile the repository | Git, Go 1.22 or later, Make, and suitable installation permissions |
| Desktop release | Users who prefer a packaged desktop application | The correct release asset for macOS, Windows, or Linux |
Install with Homebrew
Use the documented Homebrew tap and package name:
brew tap qf-studio/pilot
brew install pilotInstall with Go
If you have Go 1.22 or later and prefer the Go toolchain, use the documented module path:
go install github.com/qf-studio/pilot/cmd/pilot@latestAfter installation, make sure the directory containing Go-installed binaries is available in your shell path. The exact location depends on your Go environment, so inspect your own Go configuration rather than assuming a fixed filesystem path.
Build from source
The source installation sequence clones the repository, builds the project, and installs the resulting command globally:
git clone https://github.com/qf-studio/pilot
cd pilot
make build
sudo make install-globalSource installation includes a privileged global installation command. Inspect the repository and build targets, understand where files will be written, and use an account with only the permissions required for the installation.
Initialize and start Pilot locally
Complete the local setup before creating any public tunnel. This separation makes troubleshooting much easier. If Pilot is not initialized, cannot access its execution backend, or is not listening locally, a tunnel cannot correct those application-level problems.
Initialize Pilot configuration
Run pilot init and complete the prompts presented by your installed version. Treat provider credentials and repository access tokens as secrets. Do not place them in public documentation, tunnel descriptions, screenshots, or webhook URLs.
Start the daemon with the required integration
Pilot's documented quick start uses pilot start --github for GitHub issue polling. For a Linear deployment, use the current Pilot Linear documentation and the configuration supported by your installed version rather than substituting an unverified flag. Do not add --no-gateway when you need the HTTP gateway, because that option explicitly starts Pilot without the gateway.
Confirm the daemon and gateway are running
Check Pilot's startup output and your operating system's local listener information. The evidenced default gateway address is 127.0.0.1:9090. Confirm the actual configured address in your environment before proceeding, especially if you changed Pilot's configuration.
A listening TCP port confirms that a process has opened the local address, but it does not prove that the Linear webhook route is correct. If Pilot documents a health endpoint or provides an integration diagnostic in your installed version, use that documented mechanism. This article does not provide a speculative URL path because no universal health or Linear webhook path has been established by the supplied evidence.
First confirm that Pilot starts successfully and owns the expected local listener. Then configure Localtonet. Finally, test the exact Linear webhook route through the assigned public address. This sequence helps distinguish Pilot configuration errors from tunnel routing errors.
Why the gateway requires careful exposure
Pilot is not a passive informational website. Depending on its configuration and permissions, it can claim tickets, create branches, modify source code, run commands and tests, and open pull requests. A webhook reaching the gateway may therefore initiate work with meaningful consequences for a repository.
Use a dedicated service identity where the integration supports it. Grant access only to the repositories and operations required by the intended workflow. Keep human review and protected-branch controls in place where appropriate. If Pilot or Linear supports webhook secrets, signatures, request validation, or other authentication in your installed configuration, enable those controls according to the current Pilot documentation.
Network reachability should never be treated as authorization. A public HTTPS address allows requests to reach the configured local target, but it does not decide whether those requests are legitimate. That decision must be enforced by the receiving application and its integration configuration.
Confirm the expected Linear route and authentication behavior before registering the public URL. If those details are unclear, keep the tunnel stopped and consult the Pilot documentation for the installed release. Never invent a route, disable validation merely to make a test succeed, or place repository credentials in the webhook URL.
Create the Localtonet HTTP tunnel
Once Pilot is working locally, configure the remote-access layer. Our client must run on a device that can reach the Pilot gateway. Running it on the same machine allows the HTTP tunnel to target 127.0.0.1 directly. If the client runs elsewhere, 127.0.0.1 would refer to that other device, so you must use a local address that is genuinely reachable from the client and permitted by your network policy.
Install and run the Localtonet client
Install the Localtonet client for the operating system on the device that can reach Pilot. Start the client and keep it running. The tunnel will be available only while the selected client is connected and the tunnel itself is running.
Authenticate or select the client device
Use the device-specific authentication token associated with the client. Select the correct device in our dashboard. Never publish, guess, or embed the token in example commands or application configuration.
Select an available relay server
Choose a currently available relay server or region from the Localtonet dashboard. Available values can vary, so use the options displayed in the product rather than copying a hardcoded server code from an old tutorial.
Create an HTTP tunnel to Pilot
Create an HTTP tunnel and set its local target to the verified Pilot gateway. For the documented default on the same device, the target is IP address 127.0.0.1 and port 9090. If your Pilot configuration uses another address or port, enter the verified values from that configuration instead.
Start the tunnel and record the assigned address
Creating a tunnel does not start it. Press the Start button, wait for the tunnel to run, and use the assigned public HTTPS address. HTTP tunnels can use a generated subdomain, a selected subdomain where supported, or a custom domain. Check current documentation before configuring custom-domain DNS.
Stop or delete access when it is no longer needed
Stop the tunnel when webhook delivery is not required. Delete the configuration if the endpoint has been retired. Remember that the public address is unavailable whenever the selected client disconnects or the tunnel stops.
For the current product workflow and available dashboard options, review our Localtonet HTTP tunnel documentation .
Connect the public address to Linear
After Localtonet assigns the public HTTPS address, obtain the exact webhook route required by Pilot's current Linear adapter. Conceptually, the destination consists of the Localtonet public origin followed by the Pilot-defined path. The path is intentionally not shown here because the supplied Pilot evidence does not establish one, and guessing it could route requests incorrectly.
In Linear, create or update the webhook according to Linear's current administrative workflow and select only the events required by your Pilot configuration. Register the exact public destination, configure any secret or signature mechanism documented by Pilot, and send a controlled test event. Review Pilot's output to confirm that the request was accepted and mapped to the intended action.
A successful network request is only one part of validation. Confirm that unexpected events are rejected or ignored, that the integration cannot access unrelated repositories, and that a failed request does not trigger repeated unintended work. If a test reaches Localtonet but Pilot rejects it, investigate the Pilot route, payload, signature, and integration configuration. If the local gateway works but the public route does not, verify the selected Localtonet device, tunnel state, local IP, and port.
| Observed result | Likely area to inspect | Safe next check |
|---|---|---|
| No local listener on port 9090 | Pilot startup or gateway configuration | Review startup output and confirm that no-gateway mode was not selected |
| Local gateway works but public address does not | Localtonet client or HTTP tunnel target | Confirm the client is connected, the tunnel is started, and the target matches Pilot |
| Public request reaches Pilot but is rejected | Webhook path, payload, or authentication | Compare the Linear configuration with Pilot's current integration documentation |
| Webhook succeeds but causes an unexpected action | Event scope and Pilot permissions | Stop the tunnel, review integration settings, and reduce permissions before retesting |
Frequently asked questions
What is Pilot's default local HTTP gateway address?
The evidenced default address is 127.0.0.1:9090. Always confirm the actual listener in your installed configuration before creating the tunnel.
Does Localtonet require router port forwarding for this setup?
No. Our client establishes an outbound connection to a Localtonet relay server, so the HTTP tunnel does not require inbound router port forwarding, firewall changes, VPN setup, or a public IP address.
What Linear webhook path should I append to the public URL?
Use the exact path documented by Pilot for the installed version. The available evidence confirms Linear webhook support but does not establish a universal path, so this guide does not invent one.
Does the Localtonet URL authenticate Linear requests?
The HTTP tunnel provides network connectivity to the local service. Webhook authentication, signature verification, event validation, and authorization must be configured according to Pilot and Linear's supported mechanisms.
Must the Localtonet client run on the Pilot machine?
Not necessarily, but the client device must be able to reach the Pilot gateway. If the tunnel target is 127.0.0.1, the client and Pilot must run on the same device because that address always refers to the local device itself.
Will the webhook remain available if Pilot or the Localtonet client stops?
No. Pilot must be running and listening on the configured local target. The selected Localtonet client must also remain connected, and the HTTP tunnel must be started.
Connect your verified Pilot gateway with Localtonet
After Pilot is installed, initialized, and listening locally, create an HTTP tunnel to provide the public HTTPS origin needed for your verified Linear webhook route.
Get Started Free →
