Skip to content

The agentteams Sandboxing Guide

A rigorous, multi-projection deep-dive into how agentteams sandboxes the agents it generates — workspace write-confinement, read-exclusion, egress control, and the runtime deny-hook: how each is requested, decided, emitted, wired, enforced, tamper-tracked, and honestly bounded. It also covers the opt-in orchestrator-only write policy and its agentteams_runner MCP server (SB24, Part V), the layer that rides on that confinement so only the orchestrator — via an out-of-session runner — writes.

This guide is a focused elaboration of Part VI (OS confinement) of the broader Security Guide. It follows the same single-source method: a SKELETON fixes the facts and structure once, and four editions project it at different depths for different readers. It adds directed graphs (mermaid) that convey the request→enforce pipeline, the capability decision, the three mechanisms, the fail-open/closed hook, the integrity/drift loop, and the end-to-end synthesis.

Start here

  • The Map (SKELETON) — the single source of facts, stable section IDs (SB1…), ✅/⚙ status markers, file:line sources, the four load-bearing honest ceilings, and the canonical diagrams. Everything else projects from this.
  • Audience Profiles — how each edition renders a section (depth + voice).
  • Sources — every file:line the facts rest on.
  • Projection Guide — the rule editions follow.

Pick your edition

Edition For Depth
Reference a maintainer of the sandbox layer, or anyone who wants the whole mechanism precisely Full — every fact, file:line, and ceiling
For Developers operators who run the CLI, pick a profile, and wrap the launcher Core — which knob, what it costs, runnable commands
For Researchers security reviewers new to this stack Concept-first — the adversary, the guarantees, and their stated ceilings
For Everyone a non-technical stakeholder Light — a running analogy, plain-language ceilings, zero code

The one thing every edition keeps

The four honest ceilings, which no projection may drop or soften:

  1. Confined by default, advisory-emitted — as of 2026-W39 the default profile is confined, which emits an OS write-confinement boundary (opt out with cooperative); the deny-hook still stays fail-open by default (only an explicit confined/exclusive flips it fail-closed).
  2. Inert until wired — an emitted boundary confines nothing until the operator activates it (merges settings, sets GOOSE_SANDBOX, or wraps the process).
  3. Verified only on Linux — the launcher's bwrap branch is proven by a live-kernel deny test; the newer macOS build_macos branch is emittable but enforcement-unverified (as are the native macOS Seatbelt paths); Windows has no emittable boundary.
  4. Closes nothing absolutely — a same-host operator/key-holder (T6) and host-as-TCB stay bounded (for the write-policy layer, the runner and the operator's host are the TCB); seccomp/Landlock is a further layer not yet added.