Advanced collection

104 — Agent Sandboxing & Capability Isolation

Constrain agent-executed code and tools through independent process, filesystem, network, credential, and resource boundaries.

Concept overview

Sandboxing limits what an untrusted or compromised execution can affect. For agents, the risk includes generated code, third-party tools, retrieved instructions, and ordinary mistakes. Capability isolation grants only the particular files, endpoints, operations, and resources required for the current task.

A prompt telling the model to behave safely is not an isolation boundary. Enforcement belongs below the model in operating-system controls, container or virtual-machine boundaries, network policy, scoped service adapters, and credential brokers. The appropriate isolation strength depends on the trust level and the consequences of a boundary escape.

Why it matters in production

Proof of concept

A proof of concept may run generated analysis in a disposable environment using synthetic files and no ambient production credentials.

Production

Production requires explicit mounts, outbound network policy, nonprivileged execution, resource limits, ephemeral credentials, and validated artifact export paths.

Enterprise scale

Enterprise scale adds workload classes with different isolation strength, tenant placement policy, sandbox lifecycle controls, patching, escape testing, and capacity accounting.

Architecture components

Task capability manifest

Declares permitted inputs, outputs, endpoints, operations, and resource budgets for one execution.

Sandbox launcher

Creates an isolated process environment with constrained privileges and a disposable filesystem.

Credential broker

Issues short-lived operation-scoped credentials without exposing broad secrets to generated code.

Network and tool gateway

Enforces approved destinations, methods, resource scope, and request limits.

Artifact verifier

Inspects outputs before copying accepted artifacts into trusted storage or presenting them to users.

The architecture, mapped

Capabilities enforced outside the model — Generated code receives bounded resources; the export boundary controls what can return to trusted storage.

flowchart LR
    T["Authorized task"] --> M["Capability manifest"]
    M --> L["Sandbox launcher"]
    L --> S["Untrusted execution"]
    S --> G["Network and tool gateway"]
    G --> A["Allowed service operations"]
    S --> V["Artifact verification"]
    V --> O["Trusted output store"]
    S --> D["Revoke and destroy"]

Runtime flow

1
Classify execution
Determine whether the task runs trusted adapters, generated code, or third-party binaries and choose a suitable isolation boundary.
2
Compile capabilities
Translate authorized intent into concrete mounts, endpoints, operations, and limits; deny unspecified access by default.
3
Launch clean environment
Create a fresh sandbox without host secrets, privileged sockets, or inherited writable project directories unless explicitly required.
4
Execute bounded work
Run the task with CPU, memory, time, process, and network limits enforced outside model control.
5
Validate exported artifacts
Check paths, file types, size, and expected content before promoting outputs into the trusted workspace.
6
Destroy and account
Revoke credentials, terminate descendants, remove temporary state, and record resource usage and policy violations.

Client spreadsheet analysis workspace

Professional services · Illustrative enterprise scenario, not a reported customer outcome.

Business situation

Illustrative architecture: A delivery team asks an agent to run generated data-cleaning code on client-provided spreadsheets.

The problem

The code may read unintended host files or transmit client data if it inherits broad filesystem and network access.

Agent requirement

Permit analysis of approved inputs and export of reviewed results while isolating client data and execution resources.

Architecture

Each job receives read-only input mounts, a private scratch directory, no default network access, and a controlled artifact export service.

Runtime

Approve input manifest
launch client-scoped sandbox
run bounded analysis
reject unauthorized access
inspect output files
destroy temporary state

Failure scenario

A script tries to access a host credential path; filesystem isolation denies it and the job returns an explicit blocked-access result.

Operational impact

Measure completed authorized analyses, blocked boundary violations, cleanup success, resource consumption, and artifact validation failures without claiming isolation is infallible.

Architecture tradeoffs

Decision	Benefit	Cost
Stronger execution isolation	Reduces the reachable host and cross-tenant surface.	Adds startup latency, operational overhead, and possibly lower utilization.
Default-deny network access	Limits exfiltration and uncontrolled dependencies.	Tasks needing external data require explicit approved adapters.
Disposable environments	Reduce state leakage between tasks.	Repeated setup can increase latency and package-cache complexity.

Failure scenarios & recovery

A writable host socket is accidentally mounted.

Detect: Launch-policy validation identifies a privileged socket or forbidden mount.

Recover: Reject the sandbox specification and correct the launcher policy before execution.

A job spawns processes that survive its parent.

Detect: Lifecycle accounting detects descendants or resource usage after job completion.

Recover: Terminate the entire workload boundary and verify credential revocation and storage cleanup.

Common architecture mistakes

Treating an ordinary container as sufficient for every hostile workload.

Choose isolation based on threat model and verify host, kernel, and runtime exposure.

Giving generated code a general cloud credential.

Use a broker or adapter that enforces narrow operations and short lifetimes.

Copying every output file back automatically.

Validate paths, sizes, types, and content at a separate export boundary.

When to choose this pattern

Choose it when

Agents execute generated code or process untrusted files with complex parsers.
Multiple users or tenants share compute and storage infrastructure.
A workflow needs a concrete enforceable limit on tools, network, and resource use.

Avoid it when

The task is a pure model response with no execution or external capabilities to constrain.
Required host privileges would nullify the intended isolation boundary.
Safety-critical control requires a separately engineered real-time execution environment.

Architecture checklist

Document the threat model and selected process or virtual-machine boundary.
Deny inherited secrets, privileged sockets, and unintended host mounts.
Limit outbound destinations and service operations independently of prompts.
Enforce CPU, memory, process, storage, and elapsed-time budgets.
Use short-lived scoped credentials and test revocation after completion.
Validate artifacts before exporting them to trusted storage.
Test descendant cleanup, cross-tenant access, and sandbox policy bypass attempts.