Apra Fleet

AI agents that write code, review each other's work, and coordinate across your machines — from a single conversation.

Apra Fleet is an open-source MCP server that pairs AI coding agents into doer-reviewer loops for higher quality code, and orchestrates them across machines via SSH when you need distributed power. Works with Claude Code, Gemini, Codex and other AI coding assistants.

What you get

Doer-reviewer loops — two agents, one quality bar

Pair two agents so one writes code while the other reviews it. The built-in Project Manager orchestrates the handoff with structured checkpoints — no manual coordination needed. This works on a single machine (two local agents) or across machines.

You:   "Pair local-1 and local-2. local-1 builds the auth module, local-2 reviews."
Fleet: Doer writes code → pauses at checkpoint → Reviewer validates → feedback loop → done.

Every change gets a second pair of eyes before you even look at it.

Multi-machine orchestration — your infrastructure, one conversation

When a single machine isn't enough, Fleet coordinates agents across every machine in your network via SSH. No dashboards, no orchestration YAML — just conversation.

• Run your test suite on Linux while you develop on macOS
• Have one agent build the frontend, another the backend, a third running tests — all in parallel
• Spin up isolated workspaces on the same machine without them stepping on each other
• Use a beefy cloud VM for compilation while coding from your laptop

PM Skill — structured multi-step workflows

The optional Project Manager skill goes beyond simple task dispatch:

• Planning — breaks work into steps, gets your approval before execution
• Doer-reviewer loops — pairs agents for write-then-review workflows
• Verification checkpoints — agents pause at defined points for review
• Progress tracking — state synced via git (PLAN.md, progress.json, feedback.md)

Installed by default — both the fleet and PM skills are written on apra-fleet install. See skills/pm/SKILL.md for details.

Provider recommendations

Fleet members can run different LLM backends. Mix and match based on the role:

Role	Recommended	Why
PM (orchestrator)	Claude (Opus or Sonnet)	Most thoroughly tested for planning and multi-step orchestration
Doer	Any provider	Claude Sonnet, Gemini Flash, Codex, Copilot — mix freely
Reviewer	Premium tier models	Catches subtle issues that smaller models miss

See docs/provider-matrix.md for the full capability comparison.

Quick start

Copy-paste the one-liner for your platform:

macOS (Apple Silicon)

curl -fsSL https://github.com/Apra-Labs/apra-fleet/releases/latest/download/apra-fleet-installer-darwin-arm64 -o apra-fleet-installer && chmod +x apra-fleet-installer && ./apra-fleet-installer install

Linux (x64)

curl -fsSL https://github.com/Apra-Labs/apra-fleet/releases/latest/download/apra-fleet-installer-linux-x64 -o apra-fleet-installer && chmod +x apra-fleet-installer && ./apra-fleet-installer install

Windows (x64) — run in PowerShell:

Invoke-WebRequest -Uri https://github.com/Apra-Labs/apra-fleet/releases/latest/download/apra-fleet-installer-win-x64.exe -OutFile apra-fleet-installer.exe; .\apra-fleet-installer.exe install

Then load in Claude Code:

/mcp

Single machine — start here. No remote servers needed:

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

Remote machines — add when ready:

"Register 192.168.1.10 as build-server. Username is akhil, use password auth, work folder /home/akhil/projects/myapp."

Manual install

Download the binary for your platform from GitHub Releases:

• apra-fleet-installer-linux-x64 — Linux (x86_64)
• apra-fleet-installer-darwin-arm64 — macOS (Apple Silicon)
• apra-fleet-installer-win-x64.exe — Windows

Then run the installer:

# macOS (Apple Silicon)
chmod +x apra-fleet-installer-darwin-arm64 && ./apra-fleet-installer-darwin-arm64 install

# Linux (x64)
chmod +x apra-fleet-installer-linux-x64 && ./apra-fleet-installer-linux-x64 install

# Windows
.\apra-fleet-installer-win-x64.exe install

What install writes

Path	What it is
~/.apra-fleet/bin/apra-fleet[.exe]	The fleet binary
~/.apra-fleet/hooks/	Shell hooks (statusline, etc.)
~/.apra-fleet/scripts/	Helper scripts
~/.claude/skills/fleet/	Fleet skill (MCP tool docs for Claude)
~/.claude/skills/pm/	PM orchestration skill

The install also registers the MCP server (claude mcp add apra-fleet) and configures a status bar icon showing fleet member activity.

What install does NOT do:

• No system-level changes (no /usr/local, no PATH modification, no admin/sudo required)
• No network calls beyond claude mcp add (the binary stays local)
• No background services or daemons — the fleet server starts on-demand when Claude Code connects

The --skill flag

By default, install writes both the fleet and PM skills. Use --skill to control exactly which skills are installed:

Flag	Skills installed
install (no flag)	fleet + pm (default)
install --skill all	fleet + pm
install --skill fleet	fleet only
install --skill pm	fleet + pm (pm depends on fleet)
install --skill none	neither
install --no-skill	neither (same as --skill none)

Uninstall

Remove the files fleet wrote, then deregister the MCP server:

# macOS / Linux
rm -rf ~/.apra-fleet ~/.claude/skills/fleet ~/.claude/skills/pm
claude mcp remove apra-fleet --scope user

# Windows (PowerShell)
Remove-Item -Recurse -Force $env:USERPROFILE\.apra-fleet, $env:USERPROFILE\.claude\skills\fleet, $env:USERPROFILE\.claude\skills\pm
claude mcp remove apra-fleet --scope user

Register your first member

A "member" is any machine (or workspace) that fleet manages. There are two types:

Local member (same machine)

No SSH needed — it runs as a child process on your machine:

"Register a local member called my-project working in C:\Users\me\projects\myapp."

Remote member (another machine via SSH)

You need SSH access to the remote machine:

"Register 192.168.1.10 as build-server. Username is akhil, password is mypass, work folder /home/akhil/projects/myapp."

Fleet will test connectivity, detect the OS, and check if the LLM CLI is installed. If it isn't installed:

"Install Claude Code on build-server."

Registering with a non-Claude provider

Specify the llm_provider when registering:

"Register gemini-worker at 192.168.1.11 as a Gemini member. Work folder /home/user/work, username user, password pass."

"Register a Codex member called codex-dev locally, work folder C:\Users\me\codex-project."

Supported values: claude (default), gemini, codex, copilot.

SSH key auth

After registering a remote member with a password, migrate to key-based auth:

"Set up SSH key auth for build-server."

This generates a key pair, deploys it, verifies it works, then removes the password from storage.

Using fleet members

Run a prompt on a member

"On build-server, run the test suite and fix any failures."

The prompt is sent to the member's LLM CLI instance, which has full access to the code in its work folder.

Run a command on a member

"Run git status on build-server."

Direct shell commands without starting a Claude session — useful for quick checks.

Send files to a member

"Send config.json and deploy.sh to build-server."

Uploads files via SFTP to the member's work folder.

Check status

"Show me fleet status."

Shows all members, their status (online/offline), and last activity.

How it works

Apra Fleet is an MCP server that agentic coding systems connect to. It manages a registry of members (machines with an AI coding agent installed) and provides tools to register them, send files, execute prompts, and check status. Remote members connect via SSH. Local members run as isolated child processes on the same machine.

Tools

Member registry

Tool	Description
register_member	Register a machine as a fleet member (local or remote via SSH)
update_member	Update a member's registration (rename, change host, folder, auth, git access)
remove_member	Unregister a fleet member
list_members	List all registered fleet members
member_detail	Deep-dive status for a single member
fleet_status	Overview status of all members

Work dispatch

Tool	Description
execute_prompt	Run an AI prompt on a member (supports session resume)
execute_command	Run a shell command directly on a member (no AI CLI needed)
reset_session	Clear session ID so the next prompt starts a fresh conversation
send_files	Upload local files to a member via SFTP
receive_files	Download files from a member's work folder
monitor_task	Poll the status of a long-running background command

Auth & credentials

Tool	Description
provision_llm_auth	Deploy OAuth credentials or an API key to a member
compose_permissions	Generate and deliver provider-native permission config
setup_ssh_key	Generate an SSH key pair and migrate from password to key auth
setup_git_app	One-time setup: register a GitHub App for scoped git token minting
provision_vcs_auth	Deploy VCS credentials to a member (GitHub App, Bitbucket, Azure DevOps)
revoke_vcs_auth	Remove deployed VCS credentials from a member
credential_store_set	Store a secret credential for use in commands (entered OOB — never in chat)
credential_store_list	List stored credential names (values are never returned)
credential_store_delete	Delete a stored credential

Infrastructure

Tool	Description
cloud_control	Start, stop, or check status of cloud compute instances
update_llm_cli	Update or install the AI coding agent CLI on a member
shutdown_server	Gracefully shut down the MCP server
version	Report server version

Secure Credentials

Secrets never enter the LLM conversation or logs. Fleet's credential store keeps plaintext isolated: you enter it once in a separate terminal window, it's encrypted at rest, and commands receive it as a resolved value — never as readable text.

Three-step workflow:

# 1. Store once — Fleet opens an OOB terminal prompt, never asks in chat
credential_store_set  name=github_pat

# 2. Use in execute_command — {{secure.NAME}} is resolved only in commands, never in prompts
execute_command  command="curl -H 'Authorization: Bearer {{secure.github_pat}}' https://api.github.com/user"

# 3. Output is automatically redacted before it reaches the LLM
# Output: Authorization: Bearer [REDACTED:github_pat]

Tools that support {{secure.NAME}} token substitution:

• execute_command — shell commands on any member
• register_member — SSH password field during registration
• update_member — updating stored member passwords
• provision_vcs_auth — VCS token fields (GitHub PAT, Bitbucket token, Azure DevOps PAT)
• provision_auth — LLM API key fields

execute_prompt does not support {{secure.NAME}} — secrets must never be passed to LLM prompts. In execute_prompt, reference credentials by name only (e.g. "authenticate using credential github_pat"); the member resolves the token in its own execute_command calls.

Credential store tools:

Tool	What it does
credential_store_set	Prompt for a secret OOB and store it encrypted under a name
credential_store_list	List stored credential names — values are never returned
credential_store_delete	Remove a stored credential by name

Multi-Provider Fleets

Provisioning auth for non-Claude members

Non-Claude members require an API key — OAuth credential copy is Claude-only.

Provider	What to say
Gemini	"Provision auth for gemini-worker with API key GEMINI_API_KEY_VALUE"
Codex	"Provision auth for codex-dev with API key OPENAI_API_KEY_VALUE"
Copilot	"Provision auth for copilot-member with API key COPILOT_GITHUB_TOKEN_VALUE"

Fleet automatically uses the correct env var name per provider.

Installing CLIs on members

"Install the Gemini CLI on gemini-worker."

"Update all members' CLIs."

update_llm_cli uses the correct install/update command per provider.

Provider capabilities and limits

• max_turns is Claude-only. For Gemini, Codex, and Copilot, use timeout_ms to bound execution.
• Fine-grained permission control (compose_permissions) is Claude-only. Other providers use all-or-nothing skip-permissions flags.
• Codex output uses NDJSON internally — fleet handles this transparently.
• Gemini responses may silently truncate at ~8K tokens. Split large tasks into smaller units.
• Copilot requires a paid GitHub Copilot subscription (Pro/Business/Enterprise).

See docs/provider-matrix.md for the full comparison table.

Mix-and-match example

A fleet can have members on different providers for different purposes:

dev1     — Claude (standard)  — main implementation work
dev2     — Gemini            — tasks needing 1M context or Google Search
review1  — Claude (premium)  — code review
codex1   — Codex             — structured extraction tasks

All members use the same fleet tools — the PM dispatches to whichever member fits the task.

Git Authentication

Fleet can provision scoped, short-lived tokens to members — so each member gets only the git access it needs.

Supported providers: GitHub (App or PAT), Bitbucket (API token), Azure DevOps (PAT).

Access levels: read, push, admin, issues, full.

GitHub — Apra Labs members

The apra-fleet-git app is already installed on the Apra-Labs org. Three steps:

1. Ensure your repo is added: Go to https://github.com/organizations/Apra-Labs/settings/installations → apra-fleet-git → Configure → select your repositories. (Ask an org admin if you don't have access.)
2. Download the private key: apra-fleet-git.pem (Apra Labs internal — requires org access)
3. Register the app on your fleet instance (once per machine): "Set up git auth with app ID 3001109, installation ID 113837928, and private key at ~/Downloads/apra-fleet-git.pem."

Then provision any member:

"Provision git auth for build-server with push access to Apra-Labs/my-repo."

GitHub — GitHub App (recommended for orgs)

Setting up your own GitHub App:

1. Go to https://github.com/organizations/{your-org}/settings/apps → New GitHub App
2. Name it (e.g. "fleet-git"), set Homepage URL to anything
3. Under Permissions, grant: Contents (Read & Write), Pull Requests (Read & Write), Actions (Read) — add more as needed
4. Create the app, then Generate a private key (downloads a .pem file)
5. Install the app on your org and select which repos it can access
6. Note the App ID (from the app's settings page) and Installation ID (from the URL after installing: https://github.com/settings/installations/{installation_id})

Then tell Claude:

"Set up git auth with app ID 12345, installation ID 67890, and private key at ~/my-app.pem."

Now provision any member:

"Provision git auth for build-server with push access to Apra-Labs/my-repo."

Tokens expire after 1 hour and are re-minted automatically.

GitHub — Personal Access Token (simpler, for personal repos)

1. Go to https://github.com/settings/tokens → Generate new token
2. Select scopes: repo for full access, or fine-grained per-repo tokens

Then:

"Provision GitHub PAT auth for build-server. Token is ghp_xxxxx."

Bitbucket

1. Go to Atlassian account → App passwords → Create app password
2. Grant permissions: Repository Read/Write, Pull Request Read/Write

Then:

"Provision Bitbucket auth for build-server. Email is me@example.com, workspace is my-team, token is xxxx."

Azure DevOps

1. Go to https://dev.azure.com/{org}/_usersSettings/tokens → New Token
2. Grant scopes: Code (Read & Write), Pull Request Threads (Read & Write)

Then:

"Provision Azure DevOps auth for build-server. Org URL is https://dev.azure.com/my-org, token is xxxx."

See docs/design-git-auth.md for the full design.

Secure Password Entry

When registering a remote member with password authentication, you don't need to pass the password inline. Apra Fleet opens a separate terminal window for password entry so credentials never appear in chat history or logs.

• Password is encrypted immediately with AES-256-GCM and never stored in plaintext
• Works on macOS (Terminal.app), Windows (cmd), and Linux (gnome-terminal/xterm)
• Headless or unsupported environments get a manual command fallback
• Supports password rotation via update_member

See docs/adr-oob-password.md for the design rationale.

Cloud Compute

Fleet members can run on cloud instances (AWS EC2) that start and stop automatically based on demand. When you send a prompt to a cloud member, Apra Fleet starts the instance, waits for SSH, re-provisions credentials, and executes the work. When the member goes idle, it stops the instance to save costs.

• Auto start/stop — instances start on demand and stop after a configurable idle timeout
• GPU-aware idle detection — monitors GPU utilization via nvidia-smi so GPU workloads keep instances alive
• Long-running tasks — a task wrapper script survives SSH disconnects, supports retry with restart commands, and tracks status
• Cost tracking — real-time cost estimates based on instance type and uptime, with warnings for high spend
• Custom workload detection — define a shell command to signal busy/idle for arbitrary workloads (CPU training, downloads, etc.)

See docs/cloud-compute.md for setup and configuration details.

PM Skill (Project Manager)

The PM skill is installed by default. It's an orchestration layer for multi-step projects.

Initialize a project

"/pm init my-project"

Creates a project folder with templates for status tracking, requirements, design docs, and deployment steps.

Plan and execute

"/pm plan Implement user authentication with OAuth2"

The PM writes requirements, dispatches a member to generate an implementation plan, runs it through a review cycle, then executes it phase by phase with verification checkpoints.

Doer-reviewer loop

"/pm pair frontend-dev frontend-reviewer"

Pairs two members — one builds, one reviews. The PM handles git transport between them, sends context docs to the reviewer, and iterates until the reviewer approves.

PM commands

Command	What it does
/pm init <project>	Create project folder with templates
/pm plan <requirement>	Generate an implementation plan
/pm start <member> <plan>	Send task harness and kick off execution
/pm status <member>	Check progress
/pm resume <member>	Resume after a verification checkpoint
/pm pair <member> <member>	Pair doer and reviewer
/pm deploy <member>	Run deployment steps

Troubleshooting

Member shows as offline?

• Check if the machine is reachable: ping <ip>
• For remote members, verify SSH: ssh user@host "echo ok"
• Auth issue? Re-provision: "Provision auth for build-server"

Permission denied on a member?

• Fleet can configure member permissions. Say: "Grant build-server permission to run npm install"

Can't push workflow files or merge PRs from a member?

• Minted tokens may lack CI/CD permissions. Run these operations from your main Claude Code session instead — it has your full git credentials.

Empty response from a member?

• Usually an expired auth token. Say: "Provision auth for build-server"

Member blew past a checkpoint?

• Check what actually happened: "Run cat progress.json on build-server"

FAQ

Do I need to install apra-fleet on every device?

No. apra-fleet only needs to be installed on the device where you interact with it. All members are registered and managed from that single installation. Remote machines just need SSH access.

Does apra-fleet only work with Claude?

No. Fleet supports Claude and Gemini today, with Codex support in development. We recommend Claude as the PM's LLM provider for the best experience — it is the most thoroughly tested for planning and orchestration workflows. Gemini works well for members, especially when you want a different LLM perspective during review.

What if I only have one machine?

Fleet works great on a single machine. Use the Simple Sprint pattern with a single member, or register two local members (doer + reviewer) that run as isolated child processes. No remote servers needed.

Why use separate folders for doer and reviewer?

Agents can misbehave when they have too much context. A separate reviewer workspace provides an unbiased perspective that tends to identify more problems. Using different environments for review also validates whether the committed work can be built and run independently.

Does using fleet increase my LLM token usage?

No — fleet actively reduces token usage through three mechanisms: (1) selecting the right model tier based on task complexity, routing simple tasks to lighter models; (2) preferring shell commands via execute_command (zero tokens) over full agent prompts where possible; (3) smart conversation management that decides whether to resume existing sessions (leveraging cached context) or start fresh.

How does fleet safeguard my passwords and credentials?

Three layers: (1) out-of-band collection — passwords are entered via a shell prompt outside the conversation, so the LLM never sees them; (2) encryption at rest — stored credentials are encrypted locally, never plaintext in config files; (3) passwordless migration — fleet encourages key-based SSH auth to reduce password handling.

Is apra-fleet limited to software development?

No. Fleet is a general-purpose remote operations platform. Use cases include remote product support, simultaneous log analysis across machines, patch distribution, infrastructure automation, and even profiling and market research.

How does apra-fleet relate to Google's A2A protocol?

They're architecturally distinct and largely complementary. A2A requires each agent to run a persistent HTTP server and enables autonomous agent-to-agent delegation. Fleet requires only SSH access and uses a human-orchestrated hub-and-spoke model where the PM decides the workflow. Fleet could eventually expose members as A2A-compatible agents while preserving its SSH-based transport.

See the full FAQ for all questions, or browse the FAQ discussions.

Development

npm install && npm run build   # Build from source
npm test                       # Unit tests (vitest)
npm run build:binary           # Build single-executable binary
node dist/index.js install     # Dev-mode install (registers MCP, hooks, statusline)

Roadmap

See ROADMAP.md for planned features and good-first-issue ideas for contributors.

License

Apache 2.0 — see LICENSE for the full text.