Sovereign Fleet

Kernel-sandboxed task queue, Thompson-sampling (harness × model) router, deterministic quality gates, and mobile-first control plane for autonomous coding-agent CLIs.

What works today · Why Sovereign Fleet? · Security model · Quick start · API & MCP · Plugins · Roadmap

Why Sovereign Fleet?

Sovereign Fleet runs coding-agent CLIs (Goose, Claude Code, OpenCode, Pi, Aider) against your git repositories, one task per worktree, confined directly by the Linux kernel. It keeps every run's changes on a branch, verifies them with independent gates before landing, and gives you a queue, a model roster, an MCP server, and a phone-friendly PWA dashboard to steer it.

• Unattended without Docker overhead (Landlock ABI 6 + seccomp): Agent CLIs run with unattended flags (--no-session, acceptEdits, --auto, --yes-always) because the kernel restricts filesystem writes to the task worktree, blocks ~/.ssh and AF_UNIX sockets, and enforces an outbound TCP port allow-list.
• Decoupled (Harness × Model) Router with Quota Windows: Routes across local model servers (vLLM, SGLang, Ollama), free cloud tiers, and subscription CLIs alike. Thompson sampling ranks compatible (harness, model) pairs by cost-weighted minutes per correct result (bakeoff_priors.json), automatically rests rate-limited lanes until their quota reset, and replaces retired models with probed same-family successors.
• Verify Before Claim (Sandboxed Quality Gates): An agent's report is a claim, not proof. Every run must pass scope checks (allowed_paths + companion tests), AST syntax checks, the repository's own gate (scripts/verify.sh or pytest), and the task gate inside a credential-free sandbox before merging or opening a PR.
• Steer from Anywhere: Dispatch and approve tasks from the installable mobile Web PWA (/#token=...), from coordinator agents via the 12-tool MCP server, by replying !fleet approve <id> in Matrix, or by labelling GitHub / Gitea issues with a ```fleet contract block.

Status: alpha (0.6.0). Read What works today before relying on it.

What works today

Security model

An agent CLI is a program that runs commands chosen by a language model, and a prompt can come from anywhere a model reads. The fleet therefore assumes an agent may try anything, and limits what it can reach instead of trusting it.

• Sandbox, enforced by the kernel. Each CLI starts through python -m fleet.core.sandbox, which restricts itself and then execs the CLI. The restriction is inherited by every child and cannot be lifted:
  • Landlock filesystem rules: the task's worktree, the CLI's own state dirs (its login, sessions) and ~/.cache / ~/.npm are writable. System dirs, tool dirs (~/.nvm, ~/.local/bin, ...) and the repository's git data are read-only. Everything else, such as ~/.ssh, other credentials and the rest of your home, cannot be opened.
  • Landlock TCP rule: outgoing connections only to ports 443, 80, 53 and FLEET_SANDBOX_PORTS (for local model servers).
  • Landlock scope: no signals to processes outside, no abstract unix sockets.
  • no_new_privs: sudo and other setuid programs do not elevate.
  • seccomp: socket(AF_UNIX) and io_uring_setup fail, so an agent cannot reach the session D-Bus and start commands outside the sandbox with systemd-run --user.
  • Fails closed: without kernel support the run is refused, never run unconfined. Only FLEET_SANDBOX=0 in the executor's own environment turns it off (logged on every run). It is deliberately not a dashboard setting.
  • /tmp stays writable, so anything you keep in /tmp is readable by agents.
• Agents cannot commit, the engine does. The git data is read-only inside the sandbox (a repository under a writable path such as /tmp is the exception; there an agent's own commits are folded back into the worktree before the gates, so nothing is lost or skipped). After the run the engine restores the worktree's .git file (an agent could point it at a git dir of its own) and runs git with core.fsmonitor and hooks off, so nothing an agent wrote is executed outside the sandbox.
• Credentials stay out of the environment. API keys, tokens and SSH_AUTH_SOCK are removed from the environment the CLI starts with; a CLI reads its own login from its state dir.
• The API needs a token. Every /api route requires the API token, as Authorization: Bearer <token> or as the dashboard's session cookie (HttpOnly, SameSite=Strict, an HMAC of the token, never the token itself; cookie requests must come from the same origin). The token is FLEET_API_TOKEN, or the file ~/.config/sovereign-fleet/api_token, created with mode 0600 on first start.
• Loopback by default. fleet daemon binds 127.0.0.1. To reach it from your phone, bind your VPN address (for example a Tailscale IP) with a TLS certificate, never 0.0.0.0 on an untrusted network.

System requirements

• Operating System: Linux only (kernel >= 6.12 with Landlock ABI 6 for fail-closed filesystem and network isolation).
• Python: >= 3.11.
• Prerequisites: git and at least one agent CLI on $PATH (claude, opencode, goose, pi, or aider).
• See the Installation guide for full setup instructions and kernel verification.

Quick start

See the Installation guide for detailed requirements, kernel Landlock checks, and first-run instructions.

git clone <this repository> sovereign-fleet && cd sovereign-fleet
pip install -e ".[dev]"            # Python 3.11+
pytest                             # 511+ tests; the sandbox tests need Landlock ABI 6

fleet daemon                       # http://127.0.0.1:8444, prints where the API token is

Open http://127.0.0.1:8444, paste the token from ~/.config/sovereign-fleet/api_token.

Run one task now (the executor):

fleet run "Add input validation to the signup form" --repo ~/code/example --harness auto
# or, with the repo in fleet.toml: fleet run "..." --project example
# with a contract: stay inside the paths, prove it with this test
fleet run "Fix the off-by-one in pager.py" --project example \
  --allowed-path "src/pager.py" --gate pytest:tests/test_pager.py --category bugfix
# result: exit code, changed files, and the branch fleet/<task-id> holding the changes
git -C ~/code/example diff main...fleet/<task-id>

Queue a task over the API:

TOKEN=$(cat ~/.config/sovereign-fleet/api_token)
curl -s -X POST http://127.0.0.1:8444/api/fleet/tasks \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"text": "Refactor the auth module", "lane": "local_qwen"}'

Reach it from your phone over Tailscale (TLS with the machine's Tailscale certificate):

fleet daemon --host <tailscale-ip> --ssl-cert <name>.ts.net.crt --ssl-key <name>.ts.net.key

Sign-in by link

https://<host>:8444/#token=<token> signs a browser in: the dashboard reads the token from the URL fragment (browsers never send the fragment to the server), exchanges it for the HttpOnly session cookie and clears it from the address bar. Put that link into a QR code to sign in a phone. The access log never records a query string, so a token sent as ?token= by mistake does not reach it.

Configuration

One file, ~/.config/sovereign-fleet/fleet.toml (or $FLEET_CONFIG), holds everything specific to your machine; nothing of it is in the code. Every value is optional.

fleet config init      # writes the commented example (src/fleet/fleet.example.toml)
fleet config show      # effective values, each with its source: env, file or default
fleet config check     # repos exist, TLS files readable, token file private, no risky values

Environment variables override the file: FLEET_ROOT, FLEET_COORDINATOR, FLEET_TOKEN_FILE, FLEET_BACKEND, FLEET_GRID_RUNNER_DIR, SOVEREIGN_SECRETS, FLEET_GRID_STATUS_URL, FLEET_GRID_TOKEN_FILE; FLEET_SANDBOX_PORTS adds ports; FLEET_MODEL_CATALOG overrides routing.catalog (off switches it off); FLEET_BACKGROUND=0 turns the daemon's lane check and intake poller off. Two things are deliberately not in the file: FLEET_SANDBOX=0 (emergency only, environment of the executor) and the dashboard's runtime settings (FLEET_SETTINGS_FILE, default ~/.config/sovereign-fleet/settings.json). FLEET_API_TOKEN sets the token itself.

Issue intake

[projects.example.intake]
enabled = true
authors = ["your-login"]     # who may queue unattended tasks
label = "fleet"              # only issues with this label ("" for all)

An issue is a prompt for an agent with write access to your repository, so the intake trusts nobody by default. An issue runs unattended only when its author is in authors and it carries a ```fleet block that sets the task's contract:

add() subtracts instead of adding.

```fleet
{"allowed_paths": ["calc.py", "tests/**"], "gate": {"pytest": "tests/test_calc.py"},
 "category": "bugfix"}
```

Keys: allowed_paths (globs the change must stay inside), gate ({"pytest": path} or {"npm": script}; gate_cmd in the same form, or as "pytest <path>" / "npm run <script>", works too; anything else is rejected rather than run without its gate), category, lane (omit it and the router picks), acceptance_criteria (default: the issue's checkboxes). Every other issue (no block, an author not in authors) is queued for approval; with no authors nothing runs unattended, which is what a public repository needs. Each issue becomes one task, ever; a block that does not parse is answered once and looked at again when the issue is edited.

fleet intake status
fleet intake sync --project example --dry-run   # what would be queued; changes nothing
fleet intake sync --project example             # poll now
fleet run --task <id>                           # run an approved task in its project

The daemon polls every interval_min. The dashboard lists the sources under Settings, Issue sources (last poll, errors, "sync now", "pause"; a failing source opens itself), and marks each task that came from an issue. When a task finishes, the intake comments its result: the pull request (which closes the issue on merge), the landed commit (the issue is closed), or the failure with its cause and the lanes tried.

With the grid backend a task that needs approval is created held, so the runner never sees it pending. If that runner has its own Gitea sync, let it skip the repositories the intake reads (the reference runner reads fleet.toml for that), or every issue becomes two tasks.

Autonomy tiers

manual_gate: every new task waits for approval. safe_auto (default): a task whose text contains words like delete, drop, force, reset --hard waits for approval, others queue directly. This is a convenience filter on the task text, not a security boundary; the sandbox is. full_swarm: nothing waits.

API and MCP

All routes except /, /health, /manifest.json, /sw.js and /static/* need the token.

MCP server for coordinators (Claude Code, Cursor, Claude Desktop, Goose):

{
  "mcpServers": {
    "sovereign-fleet": {
      "command": "python3",
      "args": ["-m", "fleet.api.mcp_server"],
      "env": { "FLEET_API_URL": "http://127.0.0.1:8444" }
    }
  }
}

For Goose (~/.config/goose/config.yaml):

extensions:
  fleet:
    enabled: true
    type: stdio
    cmd: python3
    args:
    - -m
    - fleet.api.mcp_server
    timeout: 300

It reads the token like the daemon does (FLEET_API_TOKEN or the token file). Tools:

Errors come back as tool errors (isError) with the daemon's reason.

Plugins

Interfaces live in src/fleet/plugins/base.py: InputPlugin (poll_or_listen), ControlPlugin (start / stop), HarnessPlugin (execute_task), OutputPlugin (send_receipt), and CredentialPlugin (get_active_key, record_rate_limit), each with a meta property returning PluginMeta(name, kind, version, description).

A credential plugin is loaded with [plugins] credentials = "package.module:Class" (or "entrypoint" for the credentials entry in the group fleet.plugins) and used while the setting "Credential plugin" is on. The engine asks it for a lane's key by the lane's provider; after a provider limit it calls record_rate_limit, and if the plugin switched keys the lane runs once more before it rests. status() feeds the health page and must not contain secrets.

A new agent CLI is a few lines, and it is sandboxed like the built-in ones:

from pathlib import Path
from fleet.plugins.harness_base import CliHarness


class MyAgentHarness(CliHarness):
    name = "my-agent"
    binary = "my-agent"                       # looked up in PATH
    description = "My agent CLI"
    state_paths = (Path.home() / ".config/my-agent",)   # the only extra place it may write

    def build_command(self, prompt: str) -> list[str]:
        return [self.binary, "--prompt", prompt]

Register it with engine.register_harness(MyAgentHarness()) or automatically via standard Python entry points in the fleet.harnesses group. The harness gets the worktree as its working directory and as $PWD; if the CLI commits on its own, the engine folds those commits back into the worktree, so gates and landing see the change.

For a comprehensive guide covering class structure, model adaptation, Landlock sandbox enforcement, and fleet.toml tuning, see docs/HARNESS_PLUGINS.md. A complete, installable reference harness package is available in examples/custom_harness/.

The issue intake (fleet.plugins.intake) is an InputPlugin too; its trackers (GiteaTracker, GitHubTracker) implement IssueTracker (list_open, comment, close) if you need another one. Matrix output notifications and interactive approvals-by-reply live in fleet.plugins.output_matrix (configured via [matrix] in fleet.toml); the Matrix audio input plugin in src/fleet/plugins/matrix_input.py remains an optional interface sketch.

Roadmap

The package is meant to replace the grid runner it came from (docs/MIGRATION.md). The grid backend is the migration path: the app fronts the old runner today, and its parts move into the package one by one (router, gates, landing, intake), each generic and tested, until the bridge is empty.

1. Phase 5: intake. Issue intake (Gitea, GitHub) works; Matrix notifications and approvals-by-reply ([matrix]) work.
2. Phase 6: local execution and runner parity (docs/MIGRATION.md).
   • Steps 6a to 6g implemented: daemon executor loop, crash safety and recovery at start, cancel killing agent and gate process groups, failure autopsies and atomic receipts, cross-lane review loop, Matrix output and approvals, and per-project backend = "local" strangler migration (CompositeBackend).

Development

pytest                     # all tests
ruff check --select F,E9,B src tests

AGENTS.md is the contract for agents working on this repository.

Community & Support

• Nostr: Reach the operator via cipherfox@sovgrid.org or follow the grid at @sovgrid.
• Matrix: Real-time grid alerts and approvals via Matrix (configured in fleet.toml).
• Value-for-Value: Independent open-source development funded directly by operators without venture capital. Support the stack via Bitcoin Lightning or grants at sovgrid.org/support.

License

MIT