A specification for a container-host bridge: a narrow, audited channel that lets a containerised coding agent — one that deliberately has no container runtime of its own — ask its host to run a small, fixed set of orchestration commands, and get the result back.
The agent never runs the host's orchestration tooling. It writes a request file into a spool directory on the bind mount it already shares with the host. A host-side watcher notices the file, validates it against a closed allowlist, maps the verb to a fixed argument vector, runs it, and writes a response file back.
There is no network listener, no socket, no shared secret, and no new credential. The one channel that already crosses the trust boundary — the shared filesystem — is reused as the control channel.
An agent container without a runtime cannot start, stop or rebuild the stack it is working on. Historically every such action becomes a human keystroke, and autonomous work stalls waiting for one. A bridge removes the keystroke for an enumerated, reviewed set of actions without granting the agent general host execution.
Three properties make it defensible:
- Enforcement runs from a host-only copy the container cannot edit. Editing the source in the repository changes nothing until a human deliberately redeploys it.
- Placement is the authentication. The ability to write into the spool is the credential. Nothing else is needed, and nothing else would help.
- No request content ever reaches a shell. Verbs map through a closed table to fixed argument vectors; configuration is parsed, never sourced.
And one invariant holds the whole thing up:
Every request leaves the spool, for every outcome.
If a request can be left behind, a filesystem-triggered implementation re-triggers on it forever.
Normative material lives under spec/, in reading order:
| Document | Subject |
|---|---|
| 00 — Conventions | RFC 2119 keywords, requirement identifiers, terminology |
| 01 — Scope and motivation | The problem, what is in and out of scope |
| 02 — Architecture | Components, spool layout, lifecycle |
| 03 — The Two-Surface Law | Agent surface and human surface, and why they must not merge |
| 04 — Request and response contract | Schemas, filenames, states, freshness |
| 05 — Verb model | Allowlist, hardcoded denials, arguments, verb classes |
| 06 — Validation ordering | The normative order of checks |
| 07 — Security model | Pillars, trust baseline, residual risk |
| 08 — Symlink and TOCTOU defence | Pinned directory handles, safe reads, atomic publication |
| 09 — The drain invariant | Poison inputs and why every request must leave |
| 10 — Rate limiting | Sliding window, what counts, what is exempt |
| 11 — Integrity gate | Refusing to run against a changed trusted base |
| 12 — Kill switch and audit | Host-only off switch, authoritative log, mirror |
| 13 — Exit codes | The normative code table and collision handling |
| 14 — Diagnosability | Where logs live and the residual blind window |
| 15 — Operational requirements | Requirements drawn from real operational failures |
| 16 — Transport and trigger options | Filesystem watch, polling, and the trade-offs |
| 17 — Conformance | Levels, and the checks a conformant implementation passes |
| 18 — Rejected alternatives | Mechanisms considered and why they lost |
Supporting, non-normative material lives under guides/:
- Implementer's guide — how to build one, in order.
- Porting checklist — a condensed pre-flight list.
- Threat model — threats mapped to defences.
- Glossary — terms used throughout.
Version 0.1.0. Pre-1.0: the requirements are usable, but the document may still change shape. See VERSIONING.md and CHANGELOG.md.
The canonical location is:
https://github.com/LongTermSupport/spec-container-host-bridge
Cite a requirement by its identifier together with the specification version, because
identifiers are stable within a 0.x line but may be renumbered at the next minor
release before 1.0:
Container-Host Bridge specification, v0.1.0, CHB-401
https://github.com/LongTermSupport/spec-container-host-bridge
An implementation declaring conformance should state the level and version it targets — see 17 — Conformance.
- LongTermSupport/fedora-desktop provides desktop provisioning tooling including a system for running a Claude Code agent inside a container that has no container runtime. That is precisely the situation this specification addresses, and the pattern described here was developed for agents running that way.
- Edmonds-Commerce-Limited/claude-code-hooks-daemon is a hook daemon for governing what a Claude Code agent may do. An implementation of this specification SHOULD block direct container-runtime invocations inside the agent container and steer the agent to the bridge instead; a hook daemon such as that one is one way to enforce it.
Neither project is required to implement this specification, and this specification is not maintained by either.