Agent Fleet — a self-hosted console for running AI coding agents as a fleet

Agent Fleet is a web service that lets a team share AI coding agents — Claude Code, Codex CLI, GitHub Copilot CLI, Antigravity CLI, Cursor CLI, Kiro, OpenCode — efficiently and safely. Each member gets an isolated per-user environment — a Docker container with cgroup CPU/memory quotas (or a bubblewrap sandbox in the Docker-less native runtime) — with a persistent home and git working copies, and starts, drives and manages agent sessions from the browser. A Go control plane orchestrates the workspaces; the same core runs both locally (Docker) and on AWS ECS (CloudFormation) — the deployment layer is separated via ports & adapters (portability).

Status: Phase 2 complete, Phase 3 in progress. Multiple users can work in parallel, mutually invisible, on a single on-prem host (per-user Workspace / AuthGateway / network isolation / at-rest encryption). Phase 3 productization has reached the packaging & distribution milestone (P3-10): the full Console rebuild (React+Vite), the AWS ECS adapter (P3-7) and the compose / ECS / Docker-less native distribution targets are shipped, with 0.x releases published to the distribution repo (docs/history/p3-10-packaging.md, docs/roadmap.md). Current operational details and pitfalls: docs/HANDOFF.md (read first in a new session). Code: workspace/ (Agent + image) / control-plane/ / console/; start via deploy/local/run-dev.sh (subcommands: local = Docker default / wsl = WSL preset / native = no Docker / reset = wipe data. docs/dev/10 §10.3).

Self-hosting (on-prem / Docker Compose)

Each company runs one deployment on its own infrastructure. Just compose up the image set (Caddy handles automatic TLS via Let's Encrypt; login uses the CP-native Google OAuth).

cd deploy/compose
cp .env.example .env     # generate and fill in secrets (AF_MASTER_KEY etc.)
docker build -t agent-fleet/workspace:dev ../../workspace   # per-user workspace image
docker compose up -d --build

Procedures, key generation, backup/restore, upgrades, incident response and DooD constraints are collected in deploy/compose/README.md (runbook). Local dev (host processes) remains deploy/local/run-dev.sh; personal WSL use (with or without Docker) is covered by deploy/local/README-wsl.md.

A look around

Start anything from one dialog — agent, model, reasoning effort, start mode, and a fresh git worktree or the working copy as-is.	Follow and steer from the browser — questions, plans and permission prompts arrive as cards you answer in place.
Split panes — mirror, live terminal and working-tree changes side by side; each pane can also pop out into its own tab.	Real git, in the console — commit graph beside the selected commit's diff, plus staging and commit, per working copy and worktree.
See where the tokens went — per feature, per agent and per model, over 24h / 7d / 30d. Calls that report no tokens are counted separately, never as zero.	A real terminal, too — every session (agent or plain shell) is attachable as a live PTY.

The UI is English or Japanese, switched per user in ⚙ Settings — every view above also exists in Japanese (docs/img/*-ja.webp, e.g. the console). Screenshots are captured from the real Console bundle against a demo dataset — regenerate them with node console/scripts/shots/capture.mjs --locale en (the default locale is ja; how).

Settled assumptions (v1)

Topic	Decision	Rationale / notes
Claude auth	each user runs /login with their own account	the console surfaces each user's auth state and prompts re-login
User isolation	one container per user	highly portable, strong isolation, fits AWS well
Target scale	~20 users (concurrent)	a single cluster + an orchestration layer is enough
Persistence	local=bind mount / aws=EBS/EFS	home, clones, credentials and history are kept on disk
Git auth	HTTPS tokens/OAuth via Console (Connections)	downgraded from SSH keys; the CP holds no secrets (decisions/0003)
Tech stack	Console=React+Vite / Backend=Go	Go suits daemons, WS proxying and container control (decisions/0004)
Delivery model	packaged product, self-hosted per company	1 company = 1 deployment. SaaS abandoned due to ToS (decisions/0001)
Deployment layer	local / aws switchable over one core	separated via ports & adapters (local = Docker, local-first)

Documentation layout

Index: docs/README.md. Source of truth for specs = docs/dev/ (for developers) plus the code; for operations = docs/guide/ (for users); for runtime state = HANDOFF. Decisions (why) = decisions/; forward-looking plans = roadmap.md; finished plans and completed feature designs = history/.

Developer docs docs/dev/ (designs and contracts that track the code)

File	Contents
01-architecture	delivery model, terminology, 3-process layout, 2-layer auth, main flows, adapters
02-console / 03-control-plane / 04-workspace-agent	per-component design
05-api-contracts / 06-data-model	API boundaries and relaying / data model
07-security / 08-integrations	threat model, auth, crypto / external integrations
09-deploy / 10-development	deployment & portability / development practices
90-code-map / 91-internal-git	code map / internal git provider

User guide docs/guide/: split by persona (member / admin / operator / lite).

Handoff & plans

File	Contents
docs/HANDOFF.md	this host's runtime state, working practices, pitfalls, current position
docs/CHANGELOG-handoff.md	chronological log (date + one line)
docs/roadmap.md	phase list, milestones + Phase 3 detailed design (P3-1–P3-10)

The old docs/reference/ was reorganized into dev/ (mapping table in docs/README.md).

decisions/ — decision records (why, and the discarded options) — the table below is an excerpt; the full set (0001–0035) is in docs/decisions/

File	Contents
0001-self-host-vs-saas.md	delivery model: SaaS abandoned, per-company self-hosting adopted (ToS grounds, residual risk)
0002-claude-auth-onboarding.md	Claude auth: auth and onboarding are distinct (root cause of the login screen)
0003-ssh-to-connections.md	git auth: SSH keys → Connections (HTTPS tokens/OAuth)
0004-vanilla-to-react.md	Console stack: React + Vite adopted
0005-envelope-custodian.md	at-rest keys: envelope encryption + custodian abstraction (on-prem limits stated)

history/ — finished implementation plans (done, kept for the record) — the table below is an excerpt; the full set is in docs/history/

File	Contents
phase0-poc.md	Phase 0 PoC procedure (/login verification)
phase1-plan.md	Phase 1 plan + results (§11.10 remains useful knowledge)
p3-1-metadatastore.md	P3-1: MetadataStore (SQLite)
p3-2-identity-tenant.md	P3-2: identity↔tenant many-to-many
p3-3-envelope-crypto.md	P3-3: envelope encryption + custodian abstraction
p3-4-quota.md	P3-4: resource budgets / quotas
p3-5-member-console.md	P3-5: member Console UX (git/file visibility)
p3-10-packaging.md	P3-10: packaging & distribution (compose / ECS / native targets, release bundles)
console-redesign.md	Console UI rebuild brief (vanilla→React diagnosis)

Existing prototype assets (reused from)

A personal fleet-operation setup already existed; this project turns it into a product.

• oauth2-proxy — Google domain-restricted auth gate (emails.txt allowlist). Now replaced by CP-native Google OAuth (AUTH=oauth) — the allowlist is deploy/local/allowed-emails.txt (emails / @domain). Design: docs/dev/07 §7.3
• scripts/tmux-claude.sh — idempotently starts, resumes and generation-manages multiple Claude CLIs in detached tmux
• CLAUDE_CONFIG_DIR profile separation — per-directory separate ~/.claude
• ~/.claude/settings.json — remoteControlAtStartup / skipDangerousModePermissionPrompt preconfigured

Terminology

• Workspace — the persistent container environment for one user, with a home volume and running processes.
• Working copy — the working directory of a git repository cloned inside a Workspace.
• Session — the logical unit of a conversation, its settings and execution state, tied to a working copy. Codex / OpenCode can run on a shared runtime and do not necessarily own a dedicated CLI process or tmux session.

License

Apache License 2.0 (permissive, with a patent grant). Publishing the source of a credential-handling tool so each company can audit the crypto/isolation implementation is part of the adoption pitch. Contributions: CONTRIBUTING.md; vulnerability reports and the threat model: SECURITY.md.