Sandbox Isolation for Agent Build Intent

An agent with direct write access to a git branch turns your continuous‑integration pipeline into a model debugger.

When coding agents push commits straight to remote branches to see whether their changes compile, three things happen. The commit history fills with churned repair attempts. CI runner budgets burn on broken intermediate syntax. Most critically, unvetted code runs in environments that can read credentials, internal packages and build secrets.

Giving an agent raw commit authority mixes proposal with landing. Effective agent governance treats every file modification as an uncommitted proposal. The proposal must pass a strict build gate inside an isolated, ephemeral sandbox before any repository state changes.

The Cost of In‑Tree Evaluation

Evaluating writes directly in the target repository’s working tree is fragile. If an agent modifies several files, runs a local test suite, fails, and then attempts a partial fix, the working tree accumulates dirty state. Leftover artifacts, altered configuration files and half‑applied migrations bleed into subsequent runs.

The security posture is also weak. If an agent rewires a build script, adds an untrusted dependency, or writes a test that reads local environment variables, that code runs on the developer’s host and can read credentials.

Mutating the target branch should be the final step of a verified pipeline, never the workspace where validation happens.

Ephemeral Isolation at the Build Gate

A clean architecture separates the agent’s reasoning loop from the repository storage layer. When an agent decides to modify code it does not write to disk. It sends a structured payload containing the target file path, the base commit hash and the proposed contents.

Agent → Build Gate Controller
   ├─ mounts base tree read‑only
   ├─ overlays proposed diff in tmpfs
   └─ spawns network‑isolated micro‑sandbox

The controller provisions a short‑lived sandbox—typically an unprivileged container or micro‑VM. The base repository is mounted read‑only; the diff is applied on an ephemeral overlay.

Inside this boundary the build gate runs the pre‑commit invariant checks described in /blog/enforcing-pre-commit-invariant-checks-on-agent-write-intent:

1. Structural integrity – the modified files must parse into valid abstract syntax trees.
2. Compilation contracts – the project must compile without new type errors.
3. Hermetic execution – unit tests run with network egress disabled, proving the patch does not rely on unvetted external calls.

If the sandbox run fails, the harness captures stdout, stderr and compiler diagnostics, then destroys the container. The repository remains untouched and the agent receives actionable feedback.

If the sandbox run succeeds, the gate records a verification token and may apply the patch to the branch.

Balancing Latency and Environment Fidelity

Isolation introduces a trade‑off between speed and realism. Starting a full virtual machine for every edit would stall the workflow, while a pure AST check would miss broken imports and type mismatches.

The practical compromise is a tiered approach:

• In‑process syntax validation – lightweight checks run before any sandbox is started, catching malformed writes early.
• Containerised evaluation – a container started from a base image that already contains common dependencies runs the proposed diff on a transient writable layer. This step typically finishes within a few seconds, which is acceptable for interactive use.
• Network boundaries – sandboxes have egress disabled by default. If a patch needs a new external dependency, the dependency must be declared and validated through an explicit manifest check rather than being downloaded during the test run.

Sandboxes do not replace full continuous integration. End‑to‑end integration tests and multi‑service smoke tests remain in the regular CI pipeline. The isolated build gate only guarantees that a patch satisfies local invariants before it reaches the review branch.

What to Expect Next

The build‑gate method can be accessed through the MCP chatbot, the plain HTTP API, the typed TypeScript client (@shpbl/sdk) or the offline file‑based edition. All four entry points share the same gate logic and entitlement model. A free repository evaluation shows the workflow; the Practitioner tier ($39 / month) unlocks the full gate, and the Complete Master Library ($499) provides outright ownership.