Repository navigation
Guide
Generated from
docs/at cded12f. Edit the source in the repository, not this page.
This guide explains how mirafleet works, from the idea down to the code. It is written for engineers fresh out of college. You need to know basic programming and a little Go (or a similar language). You do not need to know SSH keys, SQLite, containers or MCP. The guide teaches those as they come up.
After reading it you should be able to explain the whole design, find any piece of code, run the tests, and make your first change without asking the authors.
Status: M1, M2 and M3 (workspaces) are done (13 Nov 2026), M5 (the orchestrator: MCP server, Claude Code plugin and hooks, Windows support) is built, and M4 (the admin GUI) is done. A smoke test of M5 with a real Claude Code is still to run. M6 (release and distribution: packages, image, Compose, install scripts, npm, Homebrew, signed checksums, the quickstart and the threat model) is built in the repository; the first release is
v0.6.0. To try mirafleet, follow the quickstart. This guide is also published on the project wiki (generated fromdocs/; edit the files here). M7 (host mode: remote development on a VM, central-held credentials, background jobs, full output, Claude Code tool parity; see ../M7.md) is built; the review is done, hardening is in progress and the user smoke test is still to run. Where a feature is planned, the guide says so and links the milestone in ../PLAN.md.New in M7 (read these first if you work on host mode): 1.4a, 2.14, the host runner, flows 30 to 36, 5.14 (attacking host mode) and 6.19 (migration 0004).
MIRASTACK LABS has spare servers and VMs sitting idle, and built mirafleet to put them to work
for its engineers' AI coding sessions without sharing credentials. The company has a dev fleet
and a prod fleet of servers. Engineers use an AI coding
agent (Claude Code) and want it to help run those servers. Letting an AI log in to production
with a shell is dangerous. mirafleet puts one server, central, in the middle. Each fleet
server runs a small runner that dials out to central. The agent talks to central, and central
passes along only the work that the runner's own allowlist permits. Every request is audited.
This is the same shape as GitLab CI runners. For coding work the dev fleet runs in
workspace mode: the agent gets a private container on a runner, where it may run any command
(go test, edits) without being able to reach the host, the network or anyone else's files.
The admin (aarvee) manages all of this from the command line or from a web page served by central,
the admin GUI (HTTPS, one admin account, every change audited).
Read in order the first time. Later, jump around with the map below.
| # | Chapter | What it gives you | Time |
|---|---|---|---|
| 0 | Glossary | Every term, alphabetical. Keep it open in a tab. | skim 10 min, then look things up |
| 1 | What is mirafleet? | The problem, the three roles, the big picture, the release channels (1.10), host mode (1.4a) | 25 min |
| 2 | Background | Public-key crypto, SSH, HMAC, TOTP, SQLite, context, containers (namespaces, seccomp, cgroups, egress proxy, os.Root), MCP in depth (JSON-RPC, tools, harness, plugin, skill, hook), Unix sockets, Windows DACLs, and the web basics behind the GUI (HTTP, TLS certificates, cookies, sessions, CSRF, CSP, htmx, password hashing), and release basics (semver, checksum vs signature vs provenance, SBOM, systemd user units, OCI registries, npm optional dependencies, DCO; 2.13), and for host mode (2.14) ssh-agent versus broker, secrets at rest, rotation and OS-user isolation |
105 min |
| 3 | Architecture | Components, packages, the orchestrator, the admin GUI, executors, trust boundaries (the model is untrusted input), how the parts are distributed and the protocol-level rule (M6) how they fit, and the host-mode runner (M7) | 75 min |
| 4 | Flows | Thirty-six step-by-step flows: join, register, run an action, revoke, the workspace flows (open, exec, files, close, reaper, reconcile), the MCP flows (one exec tool call, session handoff, idle on exit, SessionEnd, guarded confirm) and the GUI flows (first-start setup, login, a revoke click, session lifetime, reset-admin, a token shown once) and the host-mode flows (open, reattach, bash with paging, background jobs, credentials, re-adoption, cleanup; flows 30 to 36) |
130 min |
| 5 | Security | Every defence, the workspace container boundary, prompt injection through tool output, attacks on the GUI, the supply chain (5.13), host mode and credentials (5.14), and what would go wrong without each defence | 125 min |
| 6 | Data model | The SQLite tables (including the workspace and GUI tables), migrations, the audit log, the local files M5 added, the pre-migration backups (6.18), and migration 0004 for credentials (6.19) | 55 min |
| 7 | Protocols | SSH users, channels, framing, the JSON API | 40 min |
| 8 | Code tour | Package by package, with function names | 60 min |
| 9 | Dev setup and testing | Build, run, test, debug | 30 min |
| 10 | Operations | Install, run and look after a real deployment | 40 min |
| 11 | Contributing | Rules, review process, your first change | 20 min |
| 12 | Why mirafleet? | How it compares with CI runners, Salt, Teleport, ssh-mcp and sandboxes; where AI API keys live | 30 min |
Total: about 12.5 hours (the times above add up to about 745 minutes). If you are short on time, read 1, 3, 4 and skim 5 (start with 5.11 if you work on the MCP side, 5.12 if you work on the GUI), 2.2, 2.3, 2.7 and 2.10; that is enough to review most changes. If you only want the MCP and orchestrator story, read 2.10, the "Operator side" section of chapter 3, flows 19 to 23 in chapter 4 and section 5.11. If you only want the GUI, read 2.12, the "Admin GUI" section of chapter 3, flows 24 to 29 in chapter 4 and section 5.12.
- What is mirafleet? Why an AI agent needs a safe way to work on many servers, and what the three roles do.
- Background. The ideas from outside mirafleet that you need first, each with "why we need this", including the web basics behind the admin GUI (section 2.12) and the background for host mode (section 2.14).
- Architecture. The components, how they connect, which Go package owns what, the orchestrator on the operator's machine, the admin GUI inside central, the host-mode runner (M7) and where each key lives on each operating system.
-
Flows. Twenty-nine flows (join, register, run an action, revoke, the workspace flows:
open, exec, files, close, reaper, reconcile, revoke cascades; the MCP flows: one
exectool call, session handoff and--resume, idle on exit, SessionEnd, guardedconfirm; and the GUI flows: first-start setup, login, a revoke click, session lifetime,reset-admin, a token shown once; and the host-mode flows 30 to 36), told one numbered step at a time. - Security. The threat model, every defence layer, the workspace container boundary, prompt injection through MCP tool output (with a worked example) and attacks on the admin GUI (CSRF, DNS rebinding, XSS, brute force, stolen cookie, copied database, leaked setup token), plus host mode: credentials, the broker and agent, worked attacks, and what is not protected (5.14).
-
Data model. Tables (including
fleet_workspace,workspacesand the three GUI tables), statuses, the workspace state machine, migrations, append-only audit, and the local filescontexts.yaml,.mirafleet.yamland the session handoff file; M7 adds migration 0004 (credentials, assignments,secrets_meta, 6.19). - Protocols. The wire format: SSH users, channels, length-prefixed JSON frames.
- Code tour. Where to find things in the repository.
- Dev setup and testing. How to build and test, and the testing rules.
- Operations. Running central and runners for real.
- Contributing. How to propose, write and review a change.
- Why mirafleet? How it compares with CI runners, Salt, Teleport, ssh-mcp and sandboxes, and where AI API keys live.
Want to see it run? Chapter 9 has a "Try it locally" section: central, a runner and an
operator in one container, from central init to a real action.run.
The guide uses two kinds of diagram.
Animated SVGs show the key flows. They live in diagrams/ and are embedded like this:
How to read one:
- Each drawing loops every 6 to 12 seconds. A moving dot is a message travelling along a line.
- Numbered circles in the drawing match the numbered list directly under the image. If your viewer does not animate (or you set "reduce motion" in your operating system), the drawing shows its final state and the list tells the whole story.
- Colours follow the brand: teal is data or a request, orange is emphasis only (the thing to look at), and the status colours match runner states (active, pending, disabled, revoked).
- The drawings work in light and dark mode. They contain no scripts and load nothing from the internet.
- Every diagram has a one-line caption saying what to look at first.
Mermaid diagrams (flowcharts, sequence and state diagrams) are written as text inside the
Markdown. GitHub draws them for you. Every arrow has a label. If your viewer shows raw text
instead of a picture, the code itself is readable: A -->|label| B means "A sends label to B".
-
Running example. Company MIRASTACK LABS. Central is
central.example.com:2222. Fleets aredevandprod. Runners arebuild-1(indev) anddb-1(inprod). Operators (people who use fleets) aredurgaandkalyan. aarvee is the admin who runsmirafleet central ...on the central host. All hostnames useexample.com; nothing is real. For actions the story is durga runningtail-logsonprod/db-1. For workspaces it is aarvee creatingdevin workspace mode, then durga's Claude Code opening a workspace onbuild-1, runninggo testand reading and writing files (told in chapter 1). -
Names, not line numbers. The guide points at files and functions such as
internal/service/exec.goso it does not rot when lines move. - Planned vs built. "Planned" means not written yet.
- Glossary links. The first use of a term in a chapter links to glossary.md.
- Each chapter starts with "What you will learn" and ends with "Check your understanding" (answers hidden in a collapsed block).
- ../ARCHITECTURE.md: the formal design.
- ../PLAN.md: milestones. ../M2.md, ../M3.md, ../M4.md, ../M5.md, ../M7.md: detailed decisions.
- ../QUICKSTART.md: install and first run, per channel (M6).
- ../THREAT-MODEL.md: what is protected, from whom, and what is not (M6).
- ../RELEASING.md: the maintainer's release checklist (M6). Design: ../M6.md.
- ../BRAND.md: colours and fonts.
- ../../CLAUDE.md: ground rules for contributors and AI agents.
- STYLE.md: the rules this guide follows.
If the guide and the code disagree, the code is right. Please fix the guide.
- mirafleet quickstart
- The mirafleet developer guide
- Glossary
- 1. What is mirafleet?
- 2. Background: the ideas mirafleet builds on
- 3. Architecture
- 4. Flows
- 5. Security
- 6. Data model
- 7. Protocols
- 8. Code tour
- 9. Dev setup and testing
- 10. Operations
- 11. Contributing
- 12. Why mirafleet? A comparison with the alternatives
Generated from docs/ at cded12f; edit there.