Sandboxed developer workspaces

Read these first

• Patch application and conflict handling
• Sandbox design

What you will know

• Isolate each agent task in its own workspace

  Per-task isolation stops two agents colliding on the same working tree.

• Run parallel agents without them colliding

  Worktrees or ephemeral environments give each run its own space cheaply.

• Scope credentials so an agent cannot reach production

  Credential scoping means an agent cannot reach production from a development task.

• Clean up an ephemeral environment reliably

  Cleanup has to be reliable, or disk and containers accumulate silently.

• Demonstrate two harmless actions an unscoped agent could take that the sandbox blocks

  Use disposable files and test credentials to expose unintended filesystem or service access without touching real systems.

Chapters

1. 1

   Every run needs its own working tree, not its own clone

   Two agent runs share one clone: run A creates a branch and checks it out, and run B, mid-build, starts seeing A's files and produces a patch against a tree that never existed. A git worktree per run gives each one a private working tree and its own HEAD while sharing a single object store, so eight parallel runs against a 4GB repository do not become eight 4GB copies.

   Read chapter
2. 2

   Isolation you cannot afford is isolation you will not have

   Rank three schemes for eight concurrent tasks — a shared clone with a lock, a worktree per task, a container with a fresh clone — on cost per task and on strength of isolation. The two rankings disagree, and the disagreement is the decision: a scheme costing minutes of setup and tens of gigabytes gets routed around within a fortnight. You will also learn what a worktree does not isolate, which is most of what people assume it does.

   Read chapter
3. 3

   A worktree separates colleagues, not adversaries

   Ranking schemes on strength of isolation needs a scale behind the word, and the scale is who wrote the task. When the prompts come from your own team the failure being prevented is collision and mistake, which a worktree handles cheaply; when the task text is submitted from outside the team it is untrusted input that can steer the agent deliberately, and there a worktree stops being a boundary at all. Runs still share the object store, the .git config and its hooks, the filesystem outside the tree, the process table, the network namespace and the machine. That is the line at which the affordability argument stops applying and a container per task starts earning its cost.

   Read chapter
4. 4

   An agent started from your shell inherits every credential in it

   Run an agent on a developer's machine and it picks up the environment: an AWS profile with production access, a DATABASE_URL aimed at a production replica, whatever else happens to be exported. The correct starting point is an empty environment into which short-lived credentials scoped to the development account are injected deliberately. This chapter turns that principle into what the harness actually spawns.

   Read chapter
5. 5

   A read-only production credential is still an exfiltration route

   A teammate proposes swapping the production database URL for read-only access, arguing that reads cannot cause harm. They can: customer data entering a model's context or a log is a disclosure, and a read credential lets an agent copy a database anywhere it can reach. The same reasoning explains why a hardened container holding an organisation-wide push token has one residual risk — everything that token permits — and what a break-glass path for real data looks like.

   Read chapter
6. 6

   The safest credential is the one the agent never holds

   Short-lived and narrowly scoped is still a bearer secret: whatever the token permits, the agent can do, and can be talked into doing. The stronger position is that the agent holds no credential at all — a mediating service holds it, exposes only the specific actions a run legitimately needs, applies policy per call and logs each one. Deploying a tagged build becomes a request a broker can refuse rather than a key the agent carries anywhere it can reach. The cost is that every privileged action has to be enumerated in advance, which is also most of the benefit.

   Read chapter
7. 7

   Egress belongs behind a policy, not behind a switch

   After a security review the sandbox is given no network at all, every task starts failing during dependency installation, and the team proposes turning network back on wholesale. Neither position is the answer. Route traffic through a proxy that permits the package registries and internal services a build genuinely needs, deny everything else, and log the allows as well as the denies so the boundary can be audited rather than assumed.

   Read chapter
8. 8

   Cleanup at the end of a run is the code least likely to execute

   Four hundred tasks a day, end-of-run cleanup failing about 6% of the time, disk full every week — and the 6% badly understates the leak, because runs killed for exceeding a time budget never reach cleanup at all. Hardening a path that is skipped rather than failed buys nothing. Move removal to a separate reaper keyed on run identifier and age, make it safe to run twice on the same workspace, and name the case for deliberately keeping one.

   Read chapter
9. 9

   A review describes the boundary; only a probe finds it detached

   "No agent has ever done anything harmful" is a claim about the past, and a security sign-off establishes what a configuration was intended to do, not what the system does after six weeks of unrelated changes to base images, network policy and credential plumbing. Ship two permanent probes: a marker file written to a disposable path outside the workspace, and a connection to a test endpoint using a canary credential that grants nothing. Both must fail closed and land in the audit log.

   Read chapter