Install apra-fleet and Access It with Localtonet

Why use apra-fleet for AI agent orchestration?

Running a single coding agent is different from operating a collection of agents across several machines. Once tasks are distributed, operators must decide which member receives each job, which model or provider should perform it, how credentials are supplied, how work is isolated, and how failed or stalled processes are detected. Long-running workflows also need durable state and enough observability to understand what happened after a process ends.

apra-fleet is designed as a control plane for this operational layer. Its documented capabilities include registering Windows, macOS, and Linux machines as fleet members, working with local members or machines reached over SSH, routing work across supported model providers, and running durable workflows with supervision, reservations, watchdog behavior, and a live dashboard. The project describes software engineering as its currently active vertical, while its workflow model can also represent other decomposable tasks.

One documented workflow is fleet-sprint. It organizes development into stages such as planning, development, review, deployment, integration testing, and result harvesting. Dispatches, verdicts, costs, and child-process output can be inspected through the system's operational interfaces. These capabilities make the supervisor dashboard useful to an operator who needs to observe workflows away from the host machine.

Remote browser access should not be the first setup step, however. An external tunnel cannot fix a missing dependency, an incomplete installation, a supervisor that has not started, or a dashboard that is bound to an unexpected interface. The reliable sequence is to install apra-fleet, start it, identify the actual HTTP listener, test the dashboard locally, review its access controls, and only then configure a Localtonet HTTP tunnel for that listener.

Understand the deployment before installing

It helps to separate the supervisor, fleet members, provider integration, workflows, and remote-access path. They participate in the same deployment, but they do not have identical dependency or security requirements.

This separation matters when choosing an installation mode. A user who wants the full documented sprint workflow should prepare the Node.js and npm dependencies required by fleet-se. A user who only needs the core can explicitly install without workflows. That core-only choice is not equivalent to a default full installation, and it will not provide the omitted workflow package merely because the server starts successfully.

It also matters when exposing a service. The intended target in this guide is the browser-facing supervisor dashboard, not SSH and not an undifferentiated collection of control-plane ports. Publishing only the required HTTP endpoint reduces the externally reachable surface and makes the access path easier to audit.

Prerequisites and installation decisions

Choose between the full and core-only installations

The default install includes fleet-se, which contains fleet-sprint, the supervisor, and bd. The documented prerequisite for that default path is Node.js 22.16 or later, with npm available on the system PATH. The installer checks these requirements before proceeding and fails early when they are missing.

If you intentionally want only the apra-fleet core, use the documented --workflows none option. The project states that Node.js and npm are not required for that core-only mode. This is a meaningful deployment choice, not a workaround for an incomplete full installation.

Check Node.js and npm for the default installation

On the supervisor or orchestrator machine, run:

node --version
npm --version

For the documented full installation, the Node.js result must be 22.16 or later, and npm must resolve successfully from the same shell that will run the installer. Members that run sprints also need Node.js 22.16 or later and npm. Installing the dependency only on the supervisor is therefore insufficient when workflow execution will occur on additional members.

Prepare the machines that will become fleet members

Decide which machines will participate, what role each machine should serve, and which project directory it will use. For sprint execution, the current release notes require the member's work folder to be a Git clone with an origin remote, and its beads configuration must have a synchronization remote. The workflow checks this project identity as a precondition rather than allowing it to be bypassed.

If the fleet spans remote machines, confirm that your normal administrative connection to each machine already works before involving an agent. The project supports registering remote machines over SSH, but this guide deliberately does not invent SSH usernames, ports, keys, or trust settings. Those values belong to your own host configuration.

Plan provider and credential handling

Decide which documented provider integration you intend to install. The standard installation command defaults to Claude Code, while the installer also documents agy, opencode, codex, and copilot values through the --llm option.

Keep provider credentials and remote passwords out of prompts, shell history where practical, screenshots, issue reports, and public dashboard views. apra-fleet's documented conversational workflow collects remote passwords out of band in a separate terminal rather than exposing them to the model chat.

Prepare for Localtonet, but do not create the tunnel yet

Install the Localtonet client on the supervisor machine or another device that can reach the eventual dashboard address. You will also need a device-specific Localtonet authentication token and an available relay server selected from the current dashboard. Tokens and relay identifiers must be obtained from your account and must never be guessed, copied into this article, committed to a repository, or shown in public logs.

Install and start apra-fleet

apra-fleet offers two documented distribution paths: installation through npm and standalone installer binaries from the project's GitHub Releases page. The npm path is the clearest option when Node.js is already part of the environment. The standalone path can simplify initial delivery, but the default workflow bundle still requires the documented system Node.js and npm prerequisites.

Option A: Install through npm

npm install -g @apralabs/apra-fleet

apra-fleet install

apra-fleet install --llm agy
apra-fleet install --llm opencode
apra-fleet install --llm codex
apra-fleet install --llm copilot

apra-fleet install --workflows none

cd ~/.apra-fleet/bin && apra-fleet start

The documented path above uses a home-directory location written in POSIX shell syntax. Do not assume that the same path notation applies unchanged to every operating system or standalone installation. If your installer reports a different destination, use the destination it provides. The available evidence does not establish a universal Windows filesystem path, so this guide does not invent one.

Option B: Use a standalone installer

The project also publishes standalone installer binaries through GitHub Releases. Select the binary that the release identifies for your operating system, download it from the project's official release page, and run it. Installation is the documented default action when the binary is opened.

Confirm the release and platform before execution. If you are performing the default installation with fleet-se, the standalone delivery mechanism does not remove the requirement for system Node.js 22.16 or later and npm on PATH. If you need only the core, select the documented core-only installation mode rather than allowing the default workflow installation to fail.

Connect an agent and register fleet members

Load the fleet server in the provider environment

After installation and startup, connect the chosen MCP-capable agent to the fleet server. For Claude Code, the documented quick start instructs the operator to load the server with:

/mcp

Depending on the provider CLI, restarting that CLI may be required so it discovers the newly installed integration. The important verification is not merely that the provider program restarted. Confirm that the fleet server appears in the provider's MCP view and that the expected fleet capabilities are available.

Provider interfaces evolve independently, so this guide does not invent menu names or success messages that are not established by the apra-fleet documentation. If the integration is absent, revisit the installer option used in the previous section and make sure the provider CLI was restarted after installation.

Register local members conversationally

apra-fleet is designed to accept member-registration requests through an MCP-capable agent. The project's examples use plain-language instructions. A local setup can begin with requests such as:

Register a local member called doer.
Register another called reviewer.
Pair them.

Choose names that describe operational roles and remain understandable in logs and dashboards. Member names are labels, not security boundaries. After registration, inspect the resulting member state rather than assuming that a conversational request succeeded completely.

Register a remote member only with known host details

A documented remote-registration pattern supplies the machine's address, username, and project work folder in the request. For example, the project's quick start illustrates the intent of registering a build server and assigning a working directory. Replace every host-specific value with information from your own environment.

Do not paste passwords into agent chat. When the workflow asks for a remote password, enter it through the separate out-of-band terminal flow documented by the project. Prefer your organization's established credential policy, and grant only the repository and command permissions required by the member's role.

Validate project identity for sprint members

Current release behavior performs a fatal beads-identity check for sprint members. Each member's .beads data must belong to the project being launched. A work folder that is not a Git clone with an origin remote, or that lacks the required synchronization remote, fails the precondition. Correct the work folder and repository configuration rather than trying to bypass the check, because the release documents no bypass flag.

If you start fleet-se serve separately, the documented release behavior also requires it to find a single .beads directory. Where automatic discovery is ambiguous or unsuccessful, the project documents --beads-dir for pointing to the intended directory. Use an actual project path from your deployment rather than copying a placeholder.

Verify apra-fleet and its dashboard locally

Local verification establishes the exact target that Localtonet will publish. It should cover the running process, provider connection, fleet members, workflow dependencies, and browser dashboard.

Confirm that startup remains healthy

Keep the startup terminal visible long enough to identify immediate dependency, configuration, or binding failures. A process that exits after printing an error is not a running service. If apra-fleet runs in another process manager in your environment, inspect that manager's status and logs using your existing operational procedures.

Record any line that identifies the supervisor's listening address, port, or dashboard URL. If startup output does not show them, inspect the configuration produced by the installed version or its official version-matched documentation. The evidence supplied for this article does not establish a command that prints the dashboard endpoint, so we do not provide a speculative one.

Determine the complete local HTTP endpoint

You need four pieces of information before configuring Localtonet:

• The hostname or local IP address on which the dashboard listens.
• The TCP port used by the HTTP listener.
• Any required URL path after the host and port.
• The dashboard's authentication and session behavior.

A listener bound to a loopback address is normally reachable only from the same machine. A listener bound to another interface may be reachable from other devices on that network, subject to host and network policy. Do not change the bind address simply to accommodate a tunnel. Running the Localtonet client on the same host is often the most focused arrangement when the service intentionally listens only on loopback.

Open the dashboard from the local environment

Construct the browser address from the values reported by your installation and open it locally. Confirm that the expected live dashboard appears, not an unrelated application sharing a different port. Navigate enough of the interface to verify that workflow and member information loads rather than displaying only a static shell.

If the root address returns an error but the installation reports a specific dashboard path, use that path. If no path is reported, do not guess common routes such as /dashboard or /ui. Obtain the route from current apra-fleet output, configuration, or version-matched documentation.

Verify the provider and members

In the provider environment, confirm that the fleet MCP server is loaded. In apra-fleet, verify that the intended members appear and that their health state is consistent with the machines being online. For members expected to run sprints, check the required task tracker version:

bd version

The v0.4.3 release requires Beads bd 1.3.0 on every member that runs sprints, including the orchestrator and every doer or reviewer clone. Treat that as a release-specific requirement and review the requirements of the version you install when using a later release.

Expose the verified dashboard with Localtonet

Once the dashboard works locally, our HTTP tunnel can make that specific listener available through a public HTTPS address. The Localtonet client establishes an outbound connection to our relay, so this workflow does not require inbound router port forwarding, a public IP address, firewall changes for public ingress, or a separate VPN setup.

The tunnel remains available only while the selected Localtonet client is connected and the tunnel is running. Creating its configuration does not automatically start it. You must start it explicitly, and you can later stop or delete it when remote access is no longer required.

The public side of an HTTP tunnel uses an HTTPS address, while the local target can remain the verified local HTTP listener. This creates a focused route to the web application. It does not automatically define or replace apra-fleet's user authorization model.

Secure the dashboard and control-plane workflow

Expose only the browser-facing service you need

The clearest remote-access use case is the supervisor's HTTP dashboard. Avoid publishing SSH merely to obtain browser access, and do not expose additional MCP, database, member, or administrative listeners unless you have separately documented why they are required and how they are protected.

A narrow HTTP target improves reviewability. The tunnel configuration should identify one known local address and one known port. If the process begins listening somewhere unexpected after an upgrade, stop the tunnel and investigate instead of redirecting it experimentally across several ports.

Do not confuse transport protection with application authorization

Localtonet provides a public HTTPS address for HTTP and File Server process types, but the application behind that address still controls its own users, sessions, roles, and sensitive actions. The apra-fleet evidence available for this guide does not state whether the dashboard requires authentication or what privileges a dashboard visitor receives.

Verify the behavior of a new, unauthenticated browser session. If the page exposes workflow prompts, repository information, member details, logs, cost data, credentials, or controls without adequate authorization, do not publish it broadly. Apply least privilege and any access restrictions available in your current application and Localtonet configuration. Do not rely on obscurity or an unshared URL as the only protection.

Protect secrets across agents and members

Keep provider credentials, Localtonet device tokens, SSH secrets, repository credentials, and private endpoints outside agent prompts and public logs. Use apra-fleet's documented out-of-band secret collection for remote passwords. Review child-process logs before sharing them because workflow output can contain repository paths, commands, error messages, or other operational context.

Current apra-fleet terminology uses {{secret.NAME}}. The older {{secure.NAME}} spelling is deprecated in v0.4.3. It continues to resolve in that release but adds a deprecation notice. Update playbooks, deployment instructions, saved prompts, and sprint arguments to the current syntax rather than creating new dependencies on the deprecated form.

Stop remote access when it is not required

A Localtonet tunnel is reachable only while its selected client is connected and the tunnel is running. Stop the tunnel when remote dashboard access is no longer needed. Delete obsolete tunnel configurations and retire device tokens according to your normal credential lifecycle rather than leaving unused access paths available indefinitely.

Routine operation and upgrade planning

Use a repeatable startup and verification routine

After a host restart or maintenance event, verify the layers in order: apra-fleet process, HTTP dashboard, provider MCP connection, member health, workflow dependencies, Localtonet client, and tunnel state. This order makes failures easier to isolate. For example, an unavailable public URL may be caused by a stopped tunnel even when the local dashboard is healthy, while a Localtonet tunnel can be running correctly even though the upstream application has stopped.

Do not assume that creating a tunnel makes it persistent or active. The Localtonet device must be connected, and the selected tunnel must be running. Likewise, do not assume that a browser page proving the dashboard shell loads means all registered members or workflows are healthy.

Check versions across sprint members

Version consistency matters for a distributed fleet. The v0.4.3 release warns that mixed versions can fail during synchronization rather than at initial launch. That delayed failure can be misleading because the member may appear available until actual workflow coordination begins.

Before an upgrade, inventory the supervisor, orchestrator, doers, reviewers, and any other members that execute sprints. Confirm the required Node.js, npm, and bd versions on every applicable machine. Upgrade and validate the group as a planned fleet operation rather than changing one machine and waiting for a workflow to expose incompatibility.

Review release-specific breaking changes

For v0.4.3, scripted callers that inspect structured reason codes must account for the renamed secret-related values. The old secure_credential_not_found, secure_credential_denied, and secure_credential_expired reason codes were replaced by secret_variable_not_found, secret_variable_denied, and secret_variable_expired without aliases.

GitHub App users also need to review the release's required application permissions before upgrading. The release adds workflow write permission for certain access levels and Actions write permission for push+pr. If the App installation lacks the requested permissions, token minting fails rather than silently reducing privileges. Personal access token mode is described as unaffected by that specific GitHub App change.

If you extended apra-fleet locally and imported better-sqlite3, v0.4.3 removes that dependency because the knowledge bank uses the built-in node:sqlite implementation. Such custom extensions need a deliberate migration to DatabaseSync. The release states that no knowledge-bank data migration is required for the standard change.

Retest the dashboard and tunnel after upgrades

An upgrade can change startup behavior, configuration, dashboard paths, bind addresses, dependencies, or authentication behavior. Stop public access during a significant upgrade if your risk model requires it. Start and test apra-fleet locally, re-identify the listener, review dashboard access in a clean browser session, and then confirm that the existing Localtonet target is still correct.

Troubleshoot common installation and access problems

apra-fleet is not found after npm installation

Confirm that the global npm installation completed successfully and that the global npm executable directory is available to the current shell. Open a new terminal if your environment only refreshes PATH during shell startup. Avoid guessing an executable location or moving files manually before checking npm's own configuration for that machine.

The default installer rejects Node.js or npm

Check both commands in the same terminal used for installation:

node --version
npm --version

The documented full installation requires Node.js 22.16 or later and npm on PATH. Install or select a compatible Node.js environment, then rerun the installer. If you deliberately need only the core, use:

apra-fleet install --workflows none

Do not choose core-only mode if your actual goal depends on fleet-sprint, the supervisor, or bd.

An upgrade from 0.4.2 appears to remain on the old release

The v0.4.3 release notes describe a specific case in which running apra-fleet update from 0.4.2 on a machine without Node.js leaves 0.4.2 running. The new installer stops before changing anything, while the older updater can hide its output. The documented remedies are to install Node.js 22.16 or later first, or install the v0.4.3 core explicitly with:

apra-fleet install --force --workflows none

Treat this as release-specific guidance. For later versions, check their current upgrade notes before applying old recovery commands.

A sprint starts but later fails during synchronization

Check for mixed apra-fleet or workflow component versions across the orchestrator, doers, reviewers, and other sprint members. The release warns that mixed-version fleets can fail at synchronization rather than launch. Also run bd version on each sprint member and verify the release-required version consistently.

A member fails the beads-identity precondition

Verify that the configured work folder is the intended Git clone, that it has an origin remote, and that the beads data belongs to that project. Confirm the required synchronization remote is configured. There is no documented bypass flag for this check, so correct the project folder or configuration.

fleet-se serve cannot find the beads directory

The release documents a hard failure when the service cannot identify a single .beads directory. Run it from the intended project context or use the documented --beads-dir option to point to the correct existing directory. Do not create an arbitrary empty directory merely to satisfy discovery because the identity must correspond to the project.

The dashboard address is unknown

Review the startup output, installed configuration, and documentation matching the installed apra-fleet version. You need the actual host, port, and any URL path. The evidence available here confirms the existence of the dashboard but not universal endpoint values, so trying common development ports is not a reliable configuration method.

The dashboard works locally but not through Localtonet

Check the layers in this order:

1. Confirm that the same local dashboard URL still works on the supervisor.
2. Confirm that the Localtonet client device is connected.
3. Confirm that the selected HTTP tunnel is running, not merely created.
4. Compare the tunnel's local IP address and port with the verified dashboard listener.
5. If the Localtonet client runs on another machine, test whether that machine can reach the target address directly.
6. Check whether the application redirects the browser to a loopback or private hostname that remote visitors cannot resolve.
7. Append only the verified dashboard path if the application does not serve its interface at the root URL.

Do not change several settings simultaneously. Test after each correction so that the actual cause remains identifiable.

The public URL loads an unexpected application

Stop the tunnel and compare the configured target with apra-fleet's current listener. Another local process may be using the selected port, or a stale tunnel may still point to an old service. Confirm the application identity locally before restarting public access.

The public dashboard redirects to localhost

This generally indicates that the upstream application generated an absolute address based on its local configuration. Do not work around it by publishing additional ports. Review apra-fleet's current configuration and version-specific guidance for its public or external URL behavior. Because no such setting is established by the supplied evidence, this guide does not invent an environment variable or command-line flag.

The tunnel exists but the public address is unavailable

Verify both lifecycle conditions: the selected Localtonet client must be connected, and the tunnel must be running. A saved tunnel configuration alone does not provide an active endpoint. If you intentionally stopped the client or tunnel, start the appropriate component from the current dashboard when remote access is needed again.

Frequently asked questions