Install Pilot from Source and Expose It with Localtonet

Understand the workflow and its evidence boundary

Pilot works from tickets rather than a continuing sequence of interactive prompts. Its documented workflow can collect an issue from a supported work system, analyze the target codebase, create a branch, implement a change, run configured quality gates, and open a pull request. A person can then review the result before it is merged. GitHub polling is the concrete workflow used in this tutorial.

Source installation, Pilot configuration, provider authorization, application verification, and public exposure are separate stages. A successful Go build does not prove that Pilot can access a repository. A successful GitHub connection does not prove that Pilot is serving an HTTP endpoint. A listening HTTP server does not prove that a particular route is intended for public use. Localtonet should be introduced only after the preceding layer is understood and working.

The current Pilot sources do not present one consistent quick-start command. The repository README shows pilot init, while the current documentation landing page shows pilot setup. The documentation site also advertises networking and tunnel material, but the supplied primary evidence does not establish the gateway's bind address, port, enablement flags, public route, accepted methods, request authentication, or intended integration.

For that reason, this revision does not repeat the previous claims that Pilot automatically listens on 127.0.0.1:9090 or that a --no-gateway option controls the listener. It also does not claim that requesting / is a meaningful health test. Those details must come from documentation or configuration associated with the exact Pilot revision being operated.

Why this tutorial pins a release

Running git clone and immediately building the default branch produces whatever development revision happens to be current at that moment. That may be appropriate for contributors who deliberately want the latest source, but it is not a reproducible deployment procedure. Commands, configuration formats, flags, and endpoint behavior can change between commits.

This guide uses the published v2.281.0 release tag. The release page identifies commit 56f6983. Recording both the tag and resolved commit provides a concrete baseline for troubleshooting and review. It does not imply that Localtonet has audited Pilot's code or that the release is suitable for every production environment. You remain responsible for reviewing the release, its license, configuration, and operational behavior.

Prepare the source-build prerequisites

Pilot's repository README lists Go 1.22 or newer for source compilation and Claude Code CLI 2.1.17 or newer for its development workflow. An OpenAI API key is described as optional for voice transcription, not as a general prerequisite for compiling the Go source. The Make-based installation also needs Git, Make, a compatible shell, and permission to perform the global installation step.

Check the locally installed tools before downloading the source:

go version
git --version
make --version
claude --version

Confirm that the displayed versions satisfy Pilot's stated requirements. Install or upgrade missing dependencies through the official distribution process approved for your operating system. This article does not invent universal package-manager commands because package names, repositories, and supported installation paths differ among POSIX environments.

Claude Code authentication is separate from GitHub authorization. Make sure the Claude Code CLI works under the same operating-system account that will run Pilot. A command that works for one user may not have the same configuration, credentials, filesystem permissions, or executable path when Pilot is launched by another user or a service manager.

Pin and record Pilot v2.281.0 before building

Clone the official repository, fetch the selected release tag, and check it out in detached HEAD state. A detached checkout is useful here because it makes the build's release baseline explicit instead of placing you on a local branch that can advance accidentally.

git clone https://github.com/qf-studio/pilot
cd pilot

git fetch --tags origin
git checkout --detach v2.281.0

git rev-parse HEAD
git describe --tags --always

git status --short

{
  git rev-parse HEAD
  git describe --tags --always
} > pilot-build-revision.txt

Keep pilot-build-revision.txt with your deployment or change record. It provides a reproducible answer to the question “Which source did this binary come from?” It does not record the Go compiler version, build host, or dependency cache, so record those separately if your organization requires fuller build provenance.

Build and install the pinned Pilot source

Pilot's repository README documents two Make targets for source installation: make build followed by sudo make install-global. Run them in that order. Compilation should succeed before elevated installation is attempted.

make build

sudo make install-global

command -v pilot

If command -v pilot returns no path, inspect the installation output and your shell's PATH. If it returns a path, record it with the revision notes. Machines that have used Homebrew, go install, a desktop package, and a source installation may contain multiple copies. Updating one copy does not update the others.

Other documented installation channels

Pilot's README also lists Homebrew, go install, and desktop release packages. Those are valid alternatives for their documented platforms, but they do not reproduce the checked-out source-build procedure above. Choose an installation channel deliberately and verify which binary runs.

Reconcile Pilot setup commands and load credentials safely

Do not run both pilot init and pilot setup merely because both appear in current Pilot material. The repository README currently presents pilot init, while the current documentation landing page presents pilot setup. This is a documentation-generation difference that must be resolved against the version you actually installed.

Use the quick start from the pinned checkout

The repository content checked out at v2.281.0 belongs to the selected source baseline. Review its README and configuration documentation before initialization:

git show HEAD:README.md | sed -n '/Quick Start/,/How It Works/p'

Use the initialization command shown by that revision, not a command copied from a newer landing page. If the extracted section shows pilot init, use pilot init. If version-specific documentation instead directs you to pilot setup, use pilot setup. If the installed command and checked-out documentation disagree, stop and verify that command -v pilot points to the binary you just installed.

Load the GitHub token without typing it into a shell command

Pilot's current quick-start material establishes that the GitHub integration reads GITHUB_TOKEN, but its displayed export GITHUB_TOKEN="your-token" example encourages users to place the secret directly on a command line. Depending on the shell and how the command is entered, that can leave the token in history, terminal capture, copied snippets, or screenshots.

In an interactive Bash-compatible shell, prompt for the token without echoing it and then export the resulting variable:

IFS= read -r -s -p "GitHub token: " GITHUB_TOKEN
printf '\n'
export GITHUB_TOKEN

This keeps the token value out of the literal command text and prevents it from being displayed while entered. It does not turn an environment variable into a general-purpose secret vault. The value remains in the Pilot process environment and may be visible to sufficiently privileged local processes or diagnostic systems. Do not enable shell tracing, print the variable, save it in the repository, or include it in support output.

For a persistent service, use the secret-loading facility approved for your service manager or deployment platform rather than placing the token in a world-readable startup script. The supplied Pilot evidence does not specify one universal secret-manager integration, so this guide does not invent a Pilot-specific credential store.

Apply evidence-based least privilege

The token must be able to perform the actions required by the selected Pilot GitHub workflow in the intended repositories. That can include reading issues and source, changing issue labels, creating branches, pushing code, and opening pull requests, depending on the workflow and repository policy. The supplied primary evidence does not define an exact GitHub fine-grained permission matrix, so naming specific permission switches would be guesswork.

Use a dedicated credential where practical, restrict repository access to the repositories Pilot must operate on, avoid organization-wide or administrative access, and follow the permission guidance shipped with the pinned Pilot revision. If Pilot reports a denied GitHub operation, identify the specific failed action before broadening permissions. Do not respond by granting every available scope.

Start the documented GitHub workflow

After completing the version-appropriate initialization and loading the token, the current repository README documents GitHub polling with:

pilot start --github

Keep this process in the foreground during initial validation so that startup and authorization errors remain visible. The documentation also shows environment modes:

pilot start --env=dev --github
pilot start --env=stage --github
pilot start --env=prod --github

The documented behavior distinguishes fast development operation, stage operation that waits for CI before automatic merge, and production operation that waits for CI and human approval. Review the version-specific behavior before selecting a mode. Start with a low-risk repository and preserve human review for changes involving authentication, secrets, deployment, databases, or infrastructure.

Verify Pilot locally before considering a tunnel

Local verification should test the workflow Pilot is actually intended to perform. For GitHub polling, that means verifying the process, provider authorization, issue selection, repository access, execution backend, quality gates, and pull request result. An arbitrary HTTP request is not a substitute for those checks.

A successful bounded task proves more than a generic port check. It establishes that the installed binary, configuration, execution backend, GitHub credential, repository permissions, and project commands can work together for the selected use case.

If GitHub polling is the only feature you need, it may not require inbound requests at all. Polling means Pilot initiates outbound requests to GitHub. A public tunnel is useful only when a separate, documented Pilot integration requires another system to initiate HTTP requests toward your Pilot instance.

Establish the Pilot HTTP endpoint before exposing it

The supplied current Pilot evidence does not substantiate a universal default listener at 127.0.0.1:9090. It also does not establish a gateway-disable flag, a health route, a webhook route, a browser dashboard route, or an inbound authentication mechanism. Therefore, this tutorial cannot provide a truthful fixed Pilot host, port, or URL path.

Before creating an HTTP tunnel, locate the networking or integration instructions shipped with the pinned release and answer all of the following questions:

• Which Pilot feature requires an inbound HTTP request?
• What exact local IP address or hostname does its server bind to?
• What exact TCP port does it use?
• What URL path and HTTP method does the integration require?
• What response indicates that the route is functioning?
• How does Pilot authenticate or validate the inbound request?
• Does the external provider require a secret, signature, challenge, or callback verification?
• Does the route trigger code execution, issue creation, repository changes, or another privileged action?

If the version-specific documentation does not answer those questions, do not publish the endpoint. A process listening on a TCP port is not enough evidence that it is intended for internet exposure.

Perform a version-specific local test

Once the pinned Pilot documentation gives you a real endpoint, start Pilot and test that exact route locally using its required method and authentication. Do not substitute a request to the root path unless the documentation explicitly defines it.

A generic request template looks like this:

curl -i http://LOCAL_IP:LOCAL_PORT/DOCUMENTED_PATH

Replace every placeholder with values established by the pinned version. If the route requires headers, signatures, a challenge, or a non-GET method, follow the documented integration procedure rather than extending this generic command with guessed values.

Expose a verified Pilot HTTP endpoint with Localtonet

Continue only if you have established a legitimate inbound HTTP use case and verified its endpoint locally. Our Localtonet client should run on the device that can reach that endpoint. The client creates an outbound connection to our relay, so the workflow does not require inbound router port forwarding, firewall changes, VPN setup, or a public IP address.

If Pilot binds only to a loopback address, run our client on the same machine. Loopback always refers to the machine on which a connection originates. A Localtonet client on another computer cannot reach the Pilot host by targeting its own 127.0.0.1.

See the Localtonet HTTP tunnel documentation for the current dashboard workflow. The correct local target is not a universal Pilot value. It is the address and port verified for your selected Pilot revision and configuration.

Secure the public exposure boundary

Localtonet supplies connectivity to the configured local target. It does not replace Pilot's application authentication, request validation, authorization rules, or safe automation policy. A route that is unsafe for anonymous internet access does not become safe merely because it is reached through an outbound tunnel.

Protect every credential independently. This includes the GitHub token, Claude or other execution-backend credentials, messaging integration secrets, webhook secrets, and the Localtonet device token. Do not include them in repositories, issue bodies, pull requests, screenshots, shell tracing, or diagnostic bundles.

Review the effect of the exposed route. An endpoint that creates an issue is different from one that starts code execution, changes a repository, approves work, or triggers deployment. Apply the least privilege and human review appropriate to the most sensitive action the route can initiate.

Operate and update the combined setup

A working deployment has at least three independent lifecycle components: the Pilot process, the Localtonet client, and the HTTP tunnel. An external integration may add a fourth component. Diagnose them separately rather than treating every failure as a tunnel problem.

Starting a routine session

1. Confirm that the intended Pilot binary and revision are installed.
2. Load credentials through the approved secret-handling process.
3. Start Pilot with the reviewed integration and autonomy settings.
4. Verify a bounded local workflow or the documented local HTTP route.
5. Start the Localtonet client and confirm the intended device is connected.
6. Start the HTTP tunnel only if remote access is required.
7. Test the exact public integration route.

Stopping remote access

Stop the Localtonet tunnel when the remote workflow ends. If the configuration will not be reused, delete it. Stopping Pilot removes the local application, but explicitly stopping the tunnel makes the intended exposure state clear and avoids leaving an active public endpoint directed at an unavailable target.

Updating Pilot without losing provenance

Pilot documents an upgrade capability, but an in-place upgrade and a revision-pinned source deployment are different operational policies. If your policy requires reviewed source, select the new tag or commit explicitly, record it, build it, and repeat the verification sequence. Do not run an unreviewed update and continue labeling the installation as v2.281.0.

After an update, recheck the initialization model, configuration format, GitHub integration, autonomy settings, networking behavior, routes, and authentication. Never assume that a tunnel target or public route remains valid merely because the previous binary used it.

Troubleshoot build, configuration, and tunnel failures

The checkout does not resolve to the expected commit

Run:

git fetch --tags origin
git checkout --detach v2.281.0
git rev-parse HEAD
git describe --tags --always

Confirm that the commit begins with 56f6983. If it does not, stop before building and inspect the repository remote, tag resolution, and command output. Do not force the result to match by editing the revision record.

The source build fails

Confirm that you are in the repository root and that the selected revision is clean. Run go version and verify Go 1.22 or newer. Preserve the first meaningful compiler or dependency error because the final Make failure is often only a summary.

Avoid mixing local source edits into a release build. If git status --short reports changes, review them and either commit them as an intentionally different build or restore a clean checkout according to your source-control policy.

The global installation is denied

The documented target uses sudo make install-global. Use only approved elevation for the machine. Do not work around the failure by recursively changing broad system-directory permissions. Ask the machine administrator to install the binary or select another documented installation channel.

The shell finds the wrong Pilot binary

Run:

command -v pilot

Compare the path with the installation output. If multiple installation channels have been used, remove ambiguity before diagnosing version-dependent behavior. Restarting the shell may be necessary after a legitimate PATH change, but it will not correct an installation that wrote the binary somewhere else.

pilot init and pilot setup disagree

Return to the README and configuration material in the checked-out v2.281.0 source. Use the command associated with that revision. If the installed binary appears to follow newer documentation, verify the executable path and rebuild or reinstall the selected source. Do not run both setup paths as an experiment against important existing configuration.

Pilot cannot use GitHub

Confirm that GITHUB_TOKEN was exported in the environment that launches Pilot. A token loaded in one terminal is not automatically available to another terminal, service account, container, or process manager. Confirm that the token is valid, limited to the intended repositories, and permitted to perform the specific operation that failed.

Also check that Pilot started with --github and that the test issue has the documented pilot label. Provider polling problems are independent of Localtonet and should be resolved before any tunnel is configured.

Pilot sees the issue but cannot complete work

Check Claude Code CLI availability and authentication under the Pilot account. Review repository filesystem permissions, branch protection, project dependencies, and quality-gate commands. A provider credential can allow Pilot to read an issue while a separate local or repository restriction prevents implementation or pull request creation.

No Pilot HTTP listener can be identified

Do not assume one exists. GitHub polling is an outbound workflow and does not by itself require an inbound endpoint. Review the networking, tunnel, and integration documentation associated with the pinned release. If it does not define an address, port, route, and purpose, skip Localtonet exposure.

The local endpoint works but the public URL does not

Check each Localtonet lifecycle requirement:

• The Localtonet client is running and connected.
• The selected device token belongs to the device that can reach Pilot.
• The HTTP tunnel uses the verified local IP address and port.
• The tunnel has been started rather than only created.
• A loopback target is used only when our client runs on the same machine.
• Pilot remains active while the public test is performed.

The public address responds but the integration fails

Separate transport from application behavior. A response from the public host shows that an HTTP server was reached. It does not prove that the path, method, content type, payload, signature, challenge, or credentials satisfy the Pilot integration.

Compare the public request with the successful version-specific local test. Do not append guessed paths such as /webhook, /api, or /health. Use only the route and validation procedure documented for the installed release.

The endpoint works intermittently

Determine which component changed state. Pilot may have exited, the host may have slept, the Localtonet client may have disconnected, or the tunnel may have stopped. The endpoint requires Pilot to remain available at the configured local target while the selected Localtonet device is connected and the tunnel is running.

Frequently asked questions