hangar specs¶
Design specs for the next round of work. They came out of the first live GKE run on 2026-10-11: two Claude Code agents in gVisor sandboxes made real changes and opened PRs (#13, #14), and the run exposed the gaps these specs close. Each spec was drafted by a Claude Code agent in its own hangar sandbox, working in parallel. This page reconciles them.
North star (owner, 2026-10-12): a software factory. Coding agents run on our own infrastructure and do development work that clients, applications and services hand them, with context, while engineers follow, steer and take over. hangar is the control plane for that: environments, harnesses, sandboxes, credentials and runs are the factory floor; jobs (0009) are the front door; evals, labeling and learning are features built from the work it does.
Status (2026-10-17): built means its milestones shipped (the PR numbers are where); partly built means some of it shipped, sometimes in another shape; superseded means other work replaced it; deferred means it isn't scheduled. Each spec's own Status: line says the same. The PR column is the PR that added the spec.
| Spec | Status | Owns | PR |
|---|---|---|---|
| 0001 Agent runs | superseded: the Run model by jobs, sessions and turns (0009, 0010); liveness by the reconciler (#84) and the event watcher |
The Run record and its lifecycle states, the supervisor and liveness watcher, structured events and status, plan-usage tracking and the per-credential queue, resume_agent / cancel_agent / send_input, baked dependencies |
#16 |
| 0002 Results and landing | partly built, in another shape: verification with the repo's own check (0009, #82), landing on approval through a GitHub App (#96, #101) | The results pipeline (stage, RunResult, collection from GitHub), verification, fan-out and grading, the land step, approvals, notifiers |
#18 |
| 0003 Sandbox security | partly built: branch protection, the git credential gateway (#44), egress allowlists (#97, #107) and token scopes in another shape (admin, user, mcp, jobs, metrics, sandboxes; #122); the model-API proxy isn't scheduled |
Branch protection, the credential gateway (git smart-HTTP inspection, GitHub REST allowlist, grants, GitHub App tokens), the model-API proxy, egress allowlists, token scopes and limits, dashboard hardening | #17 |
| 0004 Supervisor, scheduling, performance | deferred: the supervisor, planner and scheduler v2 aren't scheduled; fair-share job slots shipped instead (#89) | Tasks and sub-task graphs, the deterministic supervisor and its intervention ladder, scheduler v2 (priority, fair share, plan-aware pacing, model tiers), warm-pool forecasting, image distribution, workspace checkpoints, right-sizing, benchmarks | #21 |
| 0005 Traces and decision model | deferred: the DecisionService and Decision-1 aren't scheduled; trace export moved to 0014 |
OpenTelemetry collection from harnesses, trace storage and redaction, the DecisionService (Microsoft Decision-1 first, rules and local fallbacks), decision tasks, shadow/advisory/acting modes, the optimization and evaluation loop |
#20 |
| 0006 Environments and harness packs | built: M1–M3 (#22); M4–M7 not scheduled | Image/runtime/session split, harness packs, per-sandbox harness selection, mcp: and secrets:, default and team environments |
#22 |
| 0007 Experiments, policy and team learning | deferred: the MCP gateway, the policy: block and labels aren't scheduled; experiments shipped in 0014's shape (#114); §5.4–5.6 moved to flightdeck (decision 17) |
The MCP gateway, the policy: block and where each rule is enforced, experiments over environment variants, the label taxonomy and labeler cascade, links from runs to tickets and objectives, team learnings, and the performance fixes they depend on |
#29 |
| 0008 Swarms, the improvement loop and RL | deferred: swarms, the improvement loop and RL are not for 2026; the Harbor adapter, save_as_task and ATIF moved to flightdeck (decisions 16, 17) |
swarm and sandbox pools for spreading coding work across sandboxes, memory vs filesystem fork per backend, the Harbor sandbox adapter and ATIF export, the scheduled improvement loop that ends in a PR, the labeling review tab and reports, the RL path (best-of-N → datasets → rollout backend), and reward-hacking defenses |
#29 |
| 0009 Jobs, the factory front door | built (#30 and the waves after it) | Jobs: how clients, services, MCP clients, the CLI and GitHub issues hand work to cloud agents with a context bundle; queueing, verification with the repo's own check, delivery as a branch and PR, signed callbacks, follow-ups and take-over by engineers, jobs-scoped service tokens |
#30 |
| 0010 Sessions | built (#37) | Resumable streams of work: the harness conversation, commits, uncommitted and untracked files checkpointed to the control plane (after each turn, periodically, on idle suspend and before any destroy); resume boots a fresh sandbox of the environment and continues the same conversation (claude --resume, codex exec resume, pi --session-id) or hands off a summary |
#37 |
| 0011 The factory roadmap | built (its workstreams: #40–#46) | The next slice: trusted triggers and approvals, Slack, inbound webhooks and schedules, activity events, usage and budgets, fork_session and best-of-N, the session I/O protocol (context in, progress and questions during, results, artifacts and code out), the git credential gateway, an A2A endpoint, and the position on Google AX |
#39 |
| 0012 Cutting edge: what to adopt next | partly built: items 1, 3–7 and 15 shipped (cache-aware sessions, steering, environments that live with the repo, the verify gate, PR auto-fix, egress allowlists, hangar-envd); the rest isn't scheduled |
How hangar compares with cloud coding agents (Claude Code, Codex, Cursor, Devin, Copilot and others) and sandbox platforms (E2B, Daytona, Modal, Vercel, Cloudflare, GKE Pod Snapshots) as of October 2026; which protocols to speak (MCP Apps, ACP, Claude self-hosted runners, Codex app-server, Agents SDK); measured gVisor memory fork and install caching; 15 prioritised items and the next three waves | #54 |
| 0013 E2B and CubeSandbox as references | partly built: hangar-envd, the E2B-compatible API and the e2b provider flavours; the microVM tier on GKE isn't validated live |
The envd wire protocol hangar-envd must speak, verified with the real E2B SDKs. E2B's control API, endpoint by endpoint. How CubeSandbox and E2B start fast (snapshot restore, shared page cache, reflink, eBPF). An E2B-compatible API for hangar, with CubeSandbox and self-hosted E2B as e2b provider flavours. A microVM tier on GKE nested virtualization. Where Rust pays. Phase gates per tier. Builds on 0012 (#54). |
#58 |
| 0014 The sister tool's interfaces | built (#114; the outbox, #163) | The boundary between hangar (the runtime: sandboxes, sessions, jobs, policy, emitting data) and a sister tool that interprets runs (harness inspection, trace timelines, behavior specs, evals); the three versioned interfaces it reads: the effective harness manifest (hangar.manifest/v1), trace export in OTLP/JSON on the OpenTelemetry GenAI conventions (hangar.trace/v1) and the experiment job kind (hangar.experiment/v1); what moved out of 0005 and 0007 |
#114 |
| 0015 The governance decision point | mostly built: every kind wired (#172, #173), events (#190), the passport client (#174); break-glass not yet. Tower's decision API is built | How hangar (the Run plane) asks Tower (the Govern plane) for job release, risky tool calls, landing, egress and secret approvals: the hangar.decision/v1 request and response, the client interface (governance.py: DecisionPoint, local and HTTP), timeouts, the fail-closed table, off/shadow/enforce and break-glass, overnight and outage behaviour, identity (service key, then passports), correlation, receipts, signed events, the rollout and the Tower changes it needs |
#208 |
The specs marked superseded or deferred (0001, 0004, 0005, 0007, 0008) are design history: they stay in the repo and are reachable from this table, but not from the site's navigation. The cross-spec decisions say which parts of each spec won where two conflict. One research note sits beside the specs: Google AX and Agent Substrate, an assessment for hangar (workstream G of 0011).
Where the roadmap lives¶
The phase plan that used to be here scheduled the 0001 run model, the 0004 supervisor and planner, the 0005 Decision-1 backend and the 0008 RL path; none of them was built, and the plan of 2026-10-15 puts factorials, proposers and RL out of 2026. It is in git history.
The current plan is the Run/Judge/Govern plan (hangar runs work, flightdeck judges it, Tower governs it), shown on the suite's roadmap and tracked here in the epic #119 and its linked issues. The status column above says where each spec stands.