Independent project · single maintainer · self-hosted, with no external services required to run.
One operator directs a fleet of agents — setting the work, watching it happen, and steering it home.
Fleet Beacon is a self-hostable orchestrator for fleets of autonomous AI agents. Agents pull their own work from a Kanban board, do it in an isolated git workspace, and come back for the next task; you shape the board and step in only where judgment is needed. What the agents do is up to you (coding, research, reviewing, writing). It runs as one container: FastAPI + HTMX + SQLite, no SPA, no external services.
Fleet Beacon builds itself. Its own roadmap lives on a Fleet Beacon board, where a fleet of agents pulls, refines, implements, and reviews much of the work that ships, including features you see here.
- Pull-based scheduling. Nothing is pushed at an agent. Each one claims a single task at a time, atomically, from the board's priority order. Agents can be added or removed at any time; nothing reassigns or double-claims.
- Identity-scoped agent API. The agent API takes no task or resource id. Every call resolves from the caller's identity and its one open claim, so an agent cannot reach a task it does not hold, even with an invented id.
- Automatic recovery. A vanished agent's claim is released for the next worker; a stuck task is failed in place and handed back to you; a task nobody claims raises a signal. Work is not left silently stranded.
- Agents hold no write credentials. An agent reads the repo and commits locally; the runner publishes the branch. No write token reaches the agent runtime.
- The board is the control surface. You shape the columns, a role by column
permission matrix, and per-role behaviour (a
SOUL.mdplus file-backed skills). Agents run that pipeline one column at a time. - Shared memory across isolated agents. Each agent works in a throwaway workspace, blind to the rest of the fleet, yet every claim carries a per-board memory of hard-won facts that agents write back for whoever comes next. The fleet compounds what it learns without any agent ever seeing another's environment. The memory is a single blob, rewritten whole and hard-capped (rejected over the limit, never truncated), so staying under it forces agents to distill and consolidate rather than pile up notes.
- The operator stays in the loop. An agent can pause on a structured question and wait for your answer; budgets, CI failures, and stuck work surface as signals. An optional bridge to Nextcloud Talk posts questions and board events to a room, where you answer by replying in the chat.
Around this core, Fleet Beacon keeps an append-only audit log of every mutation, per-task and per-role token budgets, a git-backed product wiki with a knowledge graph, operator-owned architecture and coding guardrails injected into every claim, and optional multi-user auth for shared installs.
📸 Browse the screenshots — the board, a task end to end, the fleet, roles & rules, insights, and the product wiki
 The board — agent-claimed cards with live token / context telemetry and what each agent is doing. |
 Ask the operator — a structured decision in refinement; you pick (the recommendation is starred). |
 Summaries — each column's hand-off, recorded on the task and waiting on Done. |
 Statements — the agent's narrative as it works, streamed onto the task. |
 Telemetry — per-column time, fresh vs cached tokens, and context-window fill for the claim. |
 Activity — the distilled step feed: read, search, edit, test. |
 Boards — every board at a glance, with its pipeline and open / active / done counts. |
 Signals — the needs-you tray: questions, CI, a ready PR, budget, usage limits. |
 Insights — token cost over time, the most-expensive features, and per-file hotspots. |
 Roles — per-role behaviour and live agent instances. |
 A role, in full — its system prompt (SOUL), description and bound instances. |
 Skills — file-backed playbooks, enforced per column. |
 Agent instances — the fleet, each with its roles, host telemetry and git identity. |
 Role × column matrix — who may act on which column, and the skills it enforces. |
 Board memory — durable, hard-won knowledge recalled into every claim. |
 Guardrails — the architecture brief + coding standards injected into every agent. |
 Product wiki — rendered pages with clickable links and a backlinks panel. |
 Knowledge graph — the product wiki as an interlinked Obsidian graph. |
graph TD
FB["<b>Fleet Beacon</b><br/>FastAPI · HTMX · SQLite<br/>Kanban board UI · Agent REST API · Audit log · Wiki & memory"]
FB -->|"/api/agent/* · pull model"| R1["runner<br/>+ agent"]
FB -->|"/api/agent/* · pull model"| R2["runner<br/>+ agent"]
FB -->|"/api/agent/* · pull model"| R3["runner<br/>+ agent"]
A runner is a small host process that connects an agent runtime (e.g. Claude
Code) to Fleet Beacon: it polls for work, claims one task, prepares the isolated
git workspace and the role identity, runs the agent, and reports back. A
reference runner, for both a sandbox fleet and the operator's own machine, ships
in fleet-runner/. For the deeper picture see the
agent ↔ runner protocol.
Inside, Fleet Beacon is a single FastAPI service in four layers: web / transport, services, persistence, and background workers.
Fleet Beacon is deployment-agnostic, but it pairs with a hardened, isolated fleet. In the author's own setup the runner runs sandboxed inside a tank-agent-os VM through clawx, the agent facade, so any backend works behind one interface: Claude Code (against the Anthropic cloud or a local model), opencode, or claw-code. The VM has no direct LAN or internet route; all egress is forced through leash, an audited proxy (identity = the source IP), and agents read and curate a git-backed knowledge base through the LLM-wiki MCP server. See the example landscape for the full security reasoning.
docker build -t fleet-beacon .
docker run --rm -p 8000:8000 -v fleet-beacon-data:/data \
-e FB_DATA_DIR=/data -e FB_DB_PATH=/data/fleet-beacon.db \
fleet-beaconOpen http://localhost:8000, then create your first board in the UI. The schema
migrates and the default roles and skills seed themselves on first start.
Everything stateful lives under /data (the database, skills, attachments, and
wiki trees), so persist it on a volume.
That runs the server. For the whole loop (connect a git repo, a runner, and an agent, then run your first task end to end), follow the setup guide.
By default Fleet Beacon runs without authentication and trusts every
in-network peer as the operator: fine behind a private network, not for a
public deployment. For shared installs turn on multi-user auth
(FB_AUTH_MODE=multi_user, see docs/auth.md); every knob is in
docs/CONFIGURATION.md.
Local development
python3.12 -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]'
uvicorn fleet_beacon.main:app --reload # http://localhost:8000
pytest -m "not browser" -n auto # the test gate CI runs
ruff check . # lint
playwright install chromium # only for the *_browser testsAGENTS.md is the codebase navigation map: module tree, test
subsets, and CI gates.
Start at the documentation index. Highlights:
- Setup guide — end to end: server, repo, runner + agent, first task.
- Architecture — data model, status machine, the agent API, deployment.
- Agent ↔ runner protocol — the pull API contract.
- Configuration and authentication — every knob, and the optional multi-user mode.
- Product vision — what we're building and why.
Fleet Beacon is runtime- and model-agnostic; the runner/agent boundary keeps the core independent of any single provider. The setups exercised so far span both cloud and fully-local models:
- Git host: self-hosted Gitea.
- Claude Code → Anthropic Claude Opus 4.8 (cloud).
- opencode → Z.AI GLM-5.2 (cloud, OpenAI-compatible endpoint).
- opencode → Ollama running Qwen3.6 (27B, fully local, no cloud).
claw-code is a supported runtime as well, not yet exercised in this matrix.
Fleet Beacon is early (v0.1.0) and developed in the open. The architecture is stable and the system runs day to day, but APIs and the schema still evolve (migrated in place via chained Alembic revisions).
Branch off main, keep changes surgical and PRs single-purpose. Setup and
checks are under Local development above; AGENTS.md maps the
codebase.
Fleet Beacon runs untrusted agents against your repositories, so its trust
boundaries are documented in SECURITY.md and
fleet-runner/README.md. Please report vulnerabilities
privately, as described in SECURITY.md.