Draft design · identity and access

Container seat design

A seat is an independent entity inside a box it cannot see out of; everything it reaches and correspondingly, everything that reaches it, is a named, reviewed crossing with a receipt. The operator's entire interface to the seat is a handful of fixed channels providing Policy Enforcement Points (PEP) and security gateways.

23 OCT 2026 · Revision 3 · draft

On this page

A seat template is a harness profile with a model named inside it. The harness process and its children are what the boundary confines; the harness reads its token, identity file and standing instructions.

The problem this design answers

An agent running as its operator can inherit that operator’s access. Its reach can include files, credentials and account-connected services that were never deliberately granted to the seat.

The design question is therefore: what wall can we put around a seat that the seat cannot reason its way through, and how do we confirm that the wall integrity is intact?

The design at a glance

Boundaries

Virtual machine

Agent seat
  • State volumeRead and write
  • Credential volumeRead only
  • Identity and policyRead only
  • InboxRead only
ProxyDestination allowlist
Permitted destinationsHub, model service and the vendor's sign-in hosts
Seat, storage and network boundaries as measured on the running seat. Files enter through the read-only inbox by a pinned copy; the hub carries only the announcement and digests. Files leave through an outbox inside the state volume, read by one pinned collector. The seat has no route to GitHub.

The seat can reach the proxy and nothing else. The proxy can reach the explicitly allowed destinations and nothing else. The seat has one writable state volume; its policy lives where its own identity cannot edit it. Credentials are supplied through a separate volume, read-only to the seat. The virtual machine sees only deliberately selected, read-only host directories.

The operator selects the virtual machine through an installed configuration and the daemon through a pinned socket. A configuration that is merely present in a recipe does not establish that the runtime consumed it.

Principles

  1. Open source and free over closed where viable. The proposed runtime is colima, an open-source container runtime.

  2. The container is the enforcement, not the harness. The design relies on the operating-system boundary, read-only mounts, a non-administrative user identity and constrained network reach. The harness’s own sandbox must be measured and reported separately.

  3. Every policy is asserted at start, never assumed. A reviewed file proves the reviewed bytes; only the running thing proves the effect.

  4. Measure the running thing, not the file. Each configuration artifact needs an identified consumer and a driving test for its effect.

  5. No secret on host disk at the operator’s shared identity. Credentials reach the seat through daemon-owned storage or are written by the harness into its own volume.

  6. One credential path, one revocation path. Each credential needs a named owner, rotation procedure and kill procedure. A credential that cannot be revoked per seat is recorded as such.

  7. Pins name bytes, not publishers. The harness and image are selected by integrity hashes. A publisher’s signature and a digest answer different questions.

  8. A count is not an identification; a null result is not a negative finding. Every absence assertion needs a positive control.

  9. Reach grows through named crossings. A seat needing more reach gets a reviewed route with a check and a refusal test; it does not receive a general opening into the host.

  10. The hub records movement; reviewed crossings move files. File checks bind an announced size and checksum to the bytes delivered.

  11. Design for the operator who is not an engineer. Preparation should expose a dry run, clear expected results and a deliberate action step, rather than require the operator to improvise configuration.

The virtual machine and runtime

The proposal uses a dedicated virtual machine per seat. Isolation between seats is by kernel and daemon, not only by container. The cost is memory. A shared virtual machine with many containers instead shares a kernel and a daemon between principals; resource observations must decide whether the dedicated design remains practical as seats are added.

The runtime configuration must be installed where the runtime actually reads it, then compared and checked against the running virtual machine. An empty mount configuration must not be interpreted as an absence of mounts without testing the runtime’s defaults.

The launcher selects its daemon in its own environment. Starting a seat must not silently change which daemon another operator session addresses.

Identity filesystem and secrets

Distinct user identity. A seat runs with an operating-system identity distinct from the operator and other seats.

Read-only root filesystem, no capabilities, no privilege escalation. The base filesystem is read-only, capabilities are removed, and gaining additional privileges is prohibited. Temporary storage does not permit executable programs or privilege-changing files.

One writable root. The state volume contains the harness’s own storage, session credential and working clone. Its ownership and write permissions must work on the first start with a fresh volume.

Read-only mounts at both layers. The virtual machine’s view of the host and the container’s view of the virtual machine are independently constrained. A driving test must demonstrate that a prohibited write is refused, with a writable control showing that the instrument itself can perform a write.

The container does not receive a daemon socket, the operator’s home directory, unrelated identity material or writable shared repository metadata. The seat commits inside its own volume; acceptance and changes to shared checkouts remain outside the seat.

Secrets through daemon-owned storage. A credential used to decide whether a seat may start is provisioned through the daemon, not through a host bind mount. A failed provision removes the unusable credential so the next start fails with the secret absent rather than consuming a partial value.

The bearer does not enter the environment. A protected helper reads the credential and supplies the authentication header. The seat’s environment must not contain bearer values.

The model credential may instead be a session obtained through an operator’s interactive sign-in and stored by the harness in its volume. The design must record whether that session can be revoked independently for each seat.

Working repositories belong inside the seat’s own state volume. A reviewed bundle can supply a copy selected at a known revision without mounting shared host checkouts. Changes leave as patches through the outbox; a separate builder applies accepted changes to the shared checkout.

No host tree that can contain a secret is mounted into a seat, even read-only. Reading can be the exposure. Host-to-virtual-machine sharing and virtual-machine-to-container mounts are separate boundaries and each needs a test of its actual effect.

A credential needed at start must arrive through a delivery path whose completeness and freshness can be checked. Failed provisioning must leave the credential absent rather than partially written. A file’s presence alone does not establish that it is usable.

The harness policy layer

Managed policy is placed in the image outside every writable volume and mount. The seat’s own writable configuration is not an enforcement boundary.

Every binding policy key needs an explicit value and an effect checked against the selected harness. An omitted key can delegate a choice to the seat. A file that loads cleanly can still contain an ineffective or unrecognised setting.

Policy concernRequired check
Model selectionA harness change must not silently change the selected model.
Sandbox and approval modesRead the resolved modes from the running harness; do not infer enforcement from a configuration file.
Sign-in method and credential storageConfirm the actual sign-in and storage behavior.
Account scopeAn unset scope remains an explicit unresolved condition until it can be established.
Update channelA harness cannot silently replace the pinned program.
Remote control and extra tool surfacesThe seat cannot restore excluded surfaces through writable configuration or launch overrides.
Tool-service configurationThe running tool set must equal the permitted set.

Configuration precedence and tool-table merging are harness-specific. If tool definitions can be added through writable configuration, the network boundary still has to refuse destinations outside the allowlist. Whether a harness offers a stronger tool-configuration lock remains a question to test, not an absence to infer from a limited search.

The network

The seat’s network has no direct outbound route. The proxy is the only reachable service, rather than merely a suggested route.

The proxy runs separately, without administrative privileges and with a read-only root filesystem. Its allowlist pairs destinations with the required connection endpoints and denies everything else. Proxy-bypass configuration must not create another route.

Tests must exercise both permitted and prohibited destinations. They must also use the actual request shapes the seat will make: a regular request and an encrypted connection tunnel do not exercise the same rule.

A proxy forwarding an unencrypted request can see its authentication header. An encrypted tunnel does not have that same visibility. This difference belongs in the design; control over the proxy does not make the exposure disappear.

The proposal does not terminate encrypted model traffic at the proxy. Doing so would create another credential and plaintext-traffic boundary to govern.

The allowlist is derived from a reviewed harness profile. The running allowlist is a reviewed, hand-maintained configuration; generation from the profile is the intended form and has not landed. Required destinations are recorded by role, including the model service, sign-in and credential refresh. A new destination changes the reviewed profile rather than being added as an unexplained proxy exception. A refresh test must exercise the same route the running harness will need.

What refuses to start

The entrypoint refuses to start the harness unless:

  1. The selected daemon answers and belongs to the intended virtual machine.
  2. The seat has the expected user identity and mount table.
  3. Its state volume is writable and prohibited storage is not.
  4. The protected credential helper produces exactly the required authentication header and refuses absent or unusable credentials.
  5. All outbound proxy settings point at the intended proxy, with no bypass or unexpected certificate override.
  6. Excluded harness features remain excluded in the harness’s own state report.
  7. The reported tool-service set equals the managed set.
  8. The expected identity material is selected by digest and actually read, not merely present.
  9. Account scope is reported, including any unresolved value.

Absence checks require positive controls. A dry run must distinguish a failed condition from a passed one. A refusal must prevent an applied start; a refusal that does not stop is only a warning.

Preparation and launch

Preparation begins with read-only checks of the selected recipe and identity. Each referenced artifact must resolve from the delivered recipe rather than from an author’s working directory.

The process installs and checks the virtual-machine configuration, builds images from pinned dependencies, provisions the credential volume, and runs driving tests against the same selected tree. Interactive sign-in remains an explicit operator step. First start and account-scope confirmation are observed before ordinary operation begins.

Launch selects the image by digest. An absent digest is a refusal, not a fallback to a movable tag. Every non-program configuration file needs an identified consumer and a test showing its effect.

Each turn of work

A console turn uses the already granted tools without changing the image or configuration. A configuration cycle changes the reviewed recipe, requires the operator’s merge decision, selects the new bytes and deliberately restarts the seat. The distinction makes the cost and authority of a turn visible before work begins.

Watching a console and typing into it are separate permissions. Observation must not accidentally answer a trust prompt or supply an instruction.

Crossings — how a contained seat does useful work

Containment must preserve useful work without granting a general route to the host. Each crossing names its direction, authority and checks.

CrossingDirectionWhat checks itWhat the hub recordsStatus
Hub messagesBothSeat authentication and the destination allowlistInstructions, announcements and resultsIn force
Outbox and collectorOutAnnounced size and checksum; a fixed collector refuses mismatched bytesAnnouncement, checksum and acceptanceIn force
InboxInA fixed delivery program supplies a reviewed file; the seat checks its checksum before readingAnnouncement and checksumIn force
RepositoriesIn, then out by reviewSelected bundles enter; patches leave through the outbox; a separate builder applies accepted changesProposed changes and the review decisionIn force (bundles in; patches out)
Code-host identityOutA push service outside the seat, holding the only code-host credentials, pushing under a per-agent identity to that agent’s branch namespace.The pull request and the operator’s merge decisionDesigned, not yet exercised
Installation into shared working treesOutAn explicit operator decision followed by a reviewed builder stepThe decision and resulting actionIn force, by operator decision

A designed crossing is one that has been ruled and specified but has not yet carried traffic; it is not counted toward acceptance.

The collector is the only route by which another seat receives files from the state volume. The producer retains the announced file until acceptance identifies the checked bytes. A read-write host directory, host shell or helper with unrestricted access to the state volume would bypass this crossing.

The reach ledger records what a crossing was needed for, what it cost to build and review, and what it caught. A refused mismatch or prohibited destination is useful evidence. The ledger is a proposed evaluation mechanism here; private records are not supplied as public proof.

Why the seat has no route to the code host

A code host is not a file store. A push can open a pull request, start a workflow run on the host’s own machines, and give that run the secrets the repository holds. A seat with push access can therefore cause code to run outside the container, with access it never had inside it. It is also the simplest route for material to leave a compromised seat: commit, push, done.

The design keeps the code host off the proxy’s allowlist. Work leaves the seat as patches through the outbox; a fixed collector refuses bytes that do not match their announced checksum; a separate builder applies accepted changes to the shared checkout. The review decision sits between the seat and the shared record because there is no path around it — a wall, not a branch-protection setting that must stay correctly configured.

The intended form of the code-host crossing is a push service: one fixed program outside every seat that collects an announced bundle, refuses a mismatch, holds the only code-host credentials, and pushes under the originating agent’s own identity to that agent’s branch namespace. It never pushes to the main branch, never rewrites history, and never starts a workflow run. Opening the pull request is the service’s act; merging remains the operator’s. Every seat gains an identity on the code host without any seat gaining a route to it. This service is designed and not yet built; until it is, the crossing stays closed.

Lessons to test, not evidence supplied

A configuration can parse and still have no effect. Tests must show that the intended consumer reads it, that the delivered artifact contains it, and that its refusal case actually refuses.

The public test plan includes configuration loaded from the wrong location, wrong virtual-machine shape, unintended host sharing, stale or partial credential delivery, missing refresh destinations, unexpected tool-service entries and failed build steps that do not stop the build. These are cases to exercise; this page does not publish an internal incident or measurement record.

Known limits and what is not yet proven

This design is not an accepted operational standard. The first seat must run under observation, and the complete operating paths must earn the criteria below. No workshop stage is assigned here.

  • The daemon is a separate authority boundary. A host process able to control the daemon can control the seat. The container wall is only as good as the authority around the service that created it.
  • Mount identity needs platform testing. A user-ownership assertion does not replace a test of actual write refusal. Each runtime must earn its own result.
  • The harness sandbox is not part of the boundary. The harness’s own sandbox is turned off in the seat’s managed configuration: it could not start under the container’s hardening, and the design does not depend on it. The container is the enforcement boundary by decision, not by default. If a later harness version’s sandbox can run inside the container, it is additional, and its enforcement is measured before it is counted.
  • Shared model sessions can prevent per-seat revocation. The registry must record the actual scope of the kill operation.
  • Unresolved account scope is a residual condition. An absent managed value may remain a choice the seat can make.
  • Tool configuration may merge additively. Managed entries alone do not prove that no other entries can appear.
  • An unencrypted hub request exposes its header to the proxy. The proxy’s authority and logging behavior need to be part of the boundary.
  • Separate identity changes the human checkpoint. Removing inherited operator credentials can remove a prompt previously seen by the operator. Deliberate approval must be placed at the run supervisor’s authority boundary.
  • A new runtime or harness version re-earns its tests. Passing checks for one combination does not establish another.
  • Public evidence is not supplied here. This page describes the proposed mechanisms and acceptance tests; it does not present the private review and observation records as publicly verifiable proof.

Observation criteria before acceptance

Acceptance requires observations of repeated bounded runs, including:

  1. Start checks remain sound, with refusal tied to a real failed condition.
  2. Prohibited writes and network destinations are refused; legitimate work succeeds without drift in storage, tools or virtual-machine configuration.
  3. Credential rotation works end to end: the previous credential fails and the replacement succeeds.
  4. A host restart preserves the declared machine shape, storage and next start.
  5. Resource readings support an explicit capacity decision for additional seats.
  6. Account scope is fixed and asserted after sign-in.
  7. Every load-bearing configuration artifact has a consumer and demonstrated effect.
  8. Crossings are exercised: a collector refuses a mismatch, the inbox carries a reviewed file, and the seat acts under its own code-host identity (not yet exercised; see Crossings).

Observation also asks whether a contained agent can work effectively with the team. The operator should record the practical effects of the boundary rather than assume that passing a checklist establishes a usable working arrangement.

A failed criterion is a design finding. The operator decides whether the design is accepted and whether migration should begin; satisfying a checklist does not make that decision automatically.

Different harnesses and migration

Network reach, filesystem reach and user identity belong to the container layer. Policy precedence, credential storage, tool configuration, update behavior and sign-in are harness-specific. A harness without an equivalent control has a gap that must be named before migration.

Each seat needs its own credential seam, policy mechanism and observation record. Existing seats remain unchanged until migration is explicitly authorised. The run supervisor’s launch target is an image digest, managed policy and a volume set; portability to another host remains something to test.

Back to the title ↑