apra-fleet

Run a fleet of AI agents across your devices, your providers, your workflows.

What Kubernetes did for containers, apra-fleet does for AI agents: scheduling, credentials, isolation, and observability for an agentic workforce -- on any machine, anywhere, using every LLM provider at once.

Quick Start - Live Demo - How It Works - Docs

This repository is built by the product you are looking at. An autonomous apra-fleet workflow plans, codes, reviews, tests, and ships this codebase in multi-hour sprints -- filing bugs against itself and fixing them. The recording above is a real run, not a mockup.

Why a fleet?

Running one AI agent is a demo. Running fifty -- across a MacBook in the office, a GPU box in the lab, three cloud VMs, and your CI -- is an operations problem nobody else has solved:

• Which machine runs which agent? Real devices, not throwaway sandboxes: registered, credentialed, health-checked members you already own.
• Which model does which job? Claude for review, a cheap tier for mechanical edits, a local vLLM model for private data -- all in one fleet, routed by cost tier, switchable per task.
• Who watches the agents? Durable workflows with supervisors, watchdogs, reservations, and live dashboards. Agents that die get detected. Work that stalls gets resumed. Nothing runs silently.
• Who holds the keys? Secrets entered out-of-band, never visible to any model. Per-provider permission composition. Network egress policy per credential.

One control plane. Any device. Any model. Any workflow. Any domain.

What you get

Watch a fleet work

Our flagship workflow, fleet-sprint, develops software autonomously: plan -> develop -> review -> deploy -> integration-test -> harvest, in cycles, until the goal is met or the evidence says stop.

It is not a toy. It builds apra-fleet itself:

• Multi-cycle sprints running for hours, unattended
• 2,300+ unit tests and an 81-file integration suite against real backends
• Files bugs against itself, decomposes them, fixes them, and blocks its own release until quality gates pass
• Every dispatch, verdict, and dollar visible live on the dashboard

A fleet that has run in production:

pm-1      Opus (premium)      orchestrator
doer-1    Sonnet (standard)   feature work
doer-2    Antigravity         large-context tasks
reviewer  Opus (premium)      final review

The engine does not know what a "sprint" is; it knows how to run your workflow reliably across your fleet (see Any domain above).

Quick start (5 minutes)

1. Install -- one command via npm (Node.js 22+), or grab the standalone installer binary for your platform from Releases and double-click it (installation is the default action):

npm install -g @apralabs/apra-fleet
apra-fleet                   # installs for Claude Code (default)
apra-fleet --llm agy         # or OpenCode/Codex/Copilot/Gemini
cd ~/.apra-fleet/bin && apra-fleet start             # start the apra-fleet

2. Connect your agent. Load the fleet server in Claude Code with /mcp (or restart your provider CLI). Your agent now has a fleet.

3. Register members -- in plain language. apra-fleet is driven conversationally through any MCP-capable agent:

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

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

Remote passwords are collected out-of-band -- typed into a separate terminal, never the chat -- used once to set up SSH keys, then forgotten.

4. Run your first workflow:

apra-fleet workflow hello-world

Then point the fleet at real work:

apra-fleet workflow fleet-sprint \
  --issue my-project-epic --members doer \
  --branch fleet-sprint/first-run --base main

Open the dashboard, watch your fleet PLAN->BUILD->REVIEW->TEST->SHIP in a loop till closure

How it works

flowchart LR
    subgraph ControlPlane["Control plane (your machine)"]
        S[Fleet server MCP or HTTP]
        W[Workflow engine]
        SUP[Supervisor - ledger, watchdog, dashboard]
    end
    subgraph Members["Fleet members (any device, anywhere)"]
        M1[MacBook - Claude]
        M2[Linux GPU box - local vLLM]
        M3[Cloud VM - Codex plus Gemini]
        M4[Windows tower - Copilot]
    end
    S ---|dispatch, files, credentials| M1
    S --- M2
    S --- M3
    S --- M4
    W --> S
    SUP --> W

• Fleet server: the control plane. Registers members, dispatches commands and prompts, moves files, brokers credentials. Speaks MCP, so any MCP-capable agent can drive a fleet.
• Members: real machines running provider CLIs. The server composes provider-native permissions before every dispatch; unattended modes are scoped, never blanket.
• Workflow engine: runs workflow programs with phases, retries, turn budgets, resumable sessions, and per-activity persistent state.
• Supervisor: the always-on layer -- launch and stop sprints over HTTP, member reservation ledger (no two workflows fight over a machine), crash watchdog, run history.

Explore with agents. Operate with programs.

There are two ways to orchestrate agents, and apra-fleet is built on the observation that you need both -- at different stages of a workflow's life:

• Exploration mode. While a workflow is still being discovered, let an LLM orchestrate: flexible, adaptive, and token-hungry -- every step is a decision, and every decision costs thinking.
• Operation mode. Once you know what must happen, the control flow becomes a deterministic workflow program. Shell, git, and file steps run through execute_command -- zero tokens. The model is invoked only at the corners that genuinely require judgment (execute_prompt): review this diff, plan this backlog, decide this exception.

That is not a projection -- it is this repository's own e2e setup+teardown step, before and after we hardened it. Development tokens are not operating tokens: pay once to discover the workflow, then run it free.

The collapse is two-dimensional. As a workflow hardens, control flow moves from model to program -- and the judgment nodes that remain move from frontier models to cheaper ones, because a well-specified task no longer needs discovery-grade reasoning. Develop a workflow with Claude; operationalize it on OpenCode against a local or OpenRouter model. Same fleet, same workflow -- swap the members. Tier routing makes it a registration change, not a rewrite.

Only a fleet makes that trade possible. Single-provider tools cannot leave their vendor; in-process frameworks cannot move orchestration out of the token path. Because apra-fleet's unit of execution is the member -- a machine plus a provider, swappable at registration -- the same hardened workflow runs on frontier models the day you design it and on commodity models every day after.

fleet-sprint is this principle, lived: it began as LLM-orchestrated exploration; each discovered pattern was hardened into the deterministic engine; today the engine drives hour-long autonomous runs in which models are consulted only as planner, doer, reviewer, tester, and harvester.

Compare to alternatives

When NOT to use it: a one-off single-file change needs no fleet.

Security model, in one paragraph

Secrets are entered out-of-band into a credential store and referenced as {{secure.NAME}} -- resolved server-side at execution, never visible to any LLM or log. Credentials scope to members, expire on TTL, and can carry a network egress policy (allow / deny / confirm). Every member runs with composed, provider-native permission files -- allow-listed tools, not god-mode. VCS access is provisioned and revocable per member.

The packages

Status and roadmap

apra-fleet is under active development -- by its own fleet. Current focus: hardening autonomous sprint execution (the toughest workflow we know of), supervisor-orchestrated multi-sprint operation, and the workflow SDK for third-party verticals.

Documentation

Community

• Questions and ideas: GitHub Discussions
• Releases: GitHub Releases
• Issues: GitHub Issues
• What is planned next: ROADMAP.md

If Apra Fleet helped you ship faster with better quality, please star the repo -- it helps others find it.

Development

Build from source (also the path for Intel Macs):

git clone https://github.com/Apra-Labs/apra-fleet && cd apra-fleet
npm install && npm run build && npm test

See CONTRIBUTING.md to contribute.

License

Apache 2.0 -- see LICENSE.

Stop babysitting agents. Start operating fleets.

Quick Start - GitHub Issues - Apra Labs