Agent runtime sandbox design limits what an AI-directed workload can read, change, execute and reach when the model is mistaken, manipulated or abused. The sandbox is not a prompt instruction telling the agent to behave. It is an enforcement environment around code execution, browser automation, file conversion, shell commands and other high-powered runtime actions. It assumes generated actions may be hostile and gives each run only the resources, identity, network paths, time and storage needed for an approved task.
The architecture must separate model planning from authority. A model can propose code or a browser step; a policy layer decides whether the task may receive a sandbox profile; the runtime enforces boundaries; brokers mediate tools and credentials; scanners inspect artifacts; and an evidence service records results. Edilec's AI agent architecture guide explains the broader loop. This guide defines the contained execution plane.
Threat-model mistakes and hostile content
Consider direct user abuse, indirect instructions embedded in websites or documents, malicious generated code, vulnerable interpreters and parsers, dependency confusion, sandbox escape, credential theft, data exfiltration, denial of service, persistence and attacks on neighboring workloads. Also model benign mistakes: deleting the wrong file, looping through paid APIs, emailing an unintended recipient or publishing an artifact with secrets. The OWASP agentic AI threats and mitigations guide provides a threat-model-based reference for emerging agentic risks.
| Risk | Boundary to enforce | Failure signal | Safe response |
|---|---|---|---|
| Host escape | Hardened runtime, minimal kernel surface and no host mounts | Unexpected syscall, privilege or host resource access | Terminate workload, isolate node and preserve runtime evidence |
| Secret theft | No ambient credentials; broker short-lived scoped tokens | Metadata endpoint or credential-path access | Deny, revoke token and investigate task context |
| Data exfiltration | Destination and protocol egress policy | Unapproved DNS, IP, upload or tunnel | Block network, retain destination and artifact digest |
| Persistence | Ephemeral filesystem and immutable base image | Scheduled job, startup change or surviving process | Destroy instance and verify pool hygiene |
| Resource exhaustion | CPU, memory, process, storage, time and cost budgets | Limit threshold or runaway loop | Kill task and return bounded failure |
| Harmful artifact | Scan and hold before release | Malware, secret, policy or active-content detection | Quarantine artifact and require review |
Use a brokered sandbox reference architecture
Place an execution broker between orchestration and the runtime. The broker authenticates the initiating user and service, evaluates task type and risk, selects an approved image and profile, creates a one-run identity, mounts only designated inputs, applies network policy and budgets, then starts the isolated workload. The workload never receives cloud control-plane credentials. Requests for approved enterprise systems go through a tool or credential broker that reauthorizes the specific resource and operation.
Return structured status, logs and artifact references through a separate channel. Scan outputs before making them downloadable or passing them to another tool. On completion, revoke credentials, terminate processes, detach storage, destroy the runtime and record cleanup. Keep the orchestration service outside the sandbox trust boundary so generated code cannot rewrite the agent's policy, traces or identity. For long tasks, checkpoint only declared artifacts and state, never an opaque privileged machine snapshot.
Choose isolation strength by workload
Process-level restrictions and containers are efficient but share more host surface. Hardened containers can suit low-sensitivity, trusted-code transformations with strong profiles and dedicated nodes. MicroVMs or equivalent lightweight virtual machines provide a stronger kernel boundary for untrusted generated code. Full virtual machines may fit legacy tools or high-isolation cases at higher startup and operational cost. Remote browsers should isolate browser processes, profiles and downloads even when no general shell is exposed.
Choose through an explicit matrix: attacker capability, input trust, data sensitivity, network need, language and package support, duration, concurrency, startup target, escape consequence and evidence. Do not advertise a runtime as a sandbox solely because it runs in a container. Verify mount, device, namespace, syscall, privilege, kernel, metadata-service and management-plane behavior. Separate high-risk profiles onto dedicated capacity where a pool-level compromise would have material impact.
Broker identity and remove ambient secrets
Give the sandbox a unique workload identity bound to run, user, tenant, task and expiry. It should authorize only the broker endpoints needed to request specific capabilities. When a tool call is approved, mint or exchange a short-lived token scoped to the target resource and action, and send it directly to the brokered connector where possible. Do not place long-lived API keys in environment variables, images, home directories, notebooks or trace payloads.
NIST's Zero Trust Architecture supports per-request decisions for subjects and resources rather than trust inherited from network placement. Apply that principle to every runtime call. Preserve initiating user, agent, sandbox and executor identities in the decision record. Edilec's agent tool permissions guide shows how resource, operation and approval constraints should remain outside model discretion.
Control egress and dependency installation
Default-deny network access and define profiles for no network, approved package mirrors, approved business APIs, or a mediated browser proxy. Enforce destination by authenticated service or stable policy, not fragile prompt wording. Control DNS, direct IP access, redirects, alternate ports, web sockets and tunneling. A URL allowlist can fail when an allowed site hosts user-controlled content; combine destination, method, content and task policy. Log denied and allowed destinations without collecting unnecessary page content.
Prebuild common dependencies into signed, scanned images. When dynamic installation is necessary, use controlled mirrors, lockfiles, hashes, package policy and a non-privileged ephemeral environment. Prevent install scripts from reaching arbitrary networks or modifying the base image. NIST SP 800-218A extends secure development practices to AI systems; signed sources, protected artifacts and reproducible environments apply to sandbox images and packages as much as model code.
Constrain storage and inspect every released artifact
Mount input files read-only under opaque names and expose only task-approved objects. Use an empty ephemeral working directory with size and inode limits. Do not mount user home directories, shared credentials, orchestration source or broad object-store buckets. Encrypt scratch storage, prevent cross-run reuse, and define deletion verification. For collaboration, copy declared outputs through a broker rather than keeping a persistent shared volume that lets one run influence another.
Before release, identify file type from content, normalize names, scan for malware and secrets, inspect active content, enforce size and archive limits, and record a digest. High-risk executable, macro-enabled or externally publishable artifacts may need human approval. Render previews in a separate untrusted viewer. If an artifact feeds another agent, retain its untrusted provenance label; successful scanning does not turn model-generated content into trusted instructions.
| Sandbox profile | Suitable tasks | Network | Storage and release |
|---|---|---|---|
| No-network transform | Parse, convert, summarize local approved files | None | Read-only inputs; scanned declared outputs |
| Package build | Compile or analyze code with known dependencies | Authenticated internal mirrors only | Ephemeral workspace; SBOM and artifact digest |
| Brokered data task | Query or update a bounded business resource | Tool broker only | No raw credential; structured result references |
| Mediated browser | Navigate approved web workflows | Browser proxy with destination policy | Fresh profile; quarantined downloads |
| High-risk code | Untrusted generated code or adversarial files | None by default; explicit one-off grants | Stronger VM boundary and dedicated pool |
| Human-approved publish | Create an external message or deliverable | Approved destination after review | Artifact scan, preview, approval and immutable record |
Prove telemetry, cleanup, and incident containment
Record run identity, image digest, profile, initiating authority, input and output references, policy decisions, broker calls, network destinations, resource consumption, scanner results, exit reason and cleanup result. Avoid dumping file contents, secrets or full browser pages into logs. Send telemetry out through a one-way controlled path that the workload cannot alter. Edilec's LLM observability checklist can connect sandbox effects to the surrounding agent trace.
Test cleanup by creating files, processes, caches, browser state and attempted persistence, then verify none appear in a later run. Test token expiry and revocation. Maintain a response path to terminate one run, quarantine an artifact, remove a runtime image, drain a node or pool, and identify all workloads using a vulnerable component. MITRE ATLAS can help responders frame adversary activity around AI-enabled execution, while conventional cloud and endpoint telemetry remains essential for host-level investigation.
Verify the sandbox before trusting it
Create abuse tests for host files, metadata endpoints, service-account tokens, neighboring processes, prohibited syscalls, privilege changes, device access, DNS and egress bypass, package mirrors, decompression bombs, fork bombs, disk exhaustion, timeout evasion, secret exfiltration and residual state. Run them after runtime, kernel, image, network or broker changes. Include normal workloads to catch controls that make the service unusable or drive teams to bypass it.
Define release criteria around enforced properties, not product names: no ambient cloud identity, no host mount, bounded resources, default-deny egress, immutable approved base, isolated scratch, controlled output, attributable policy and verified teardown. Commission independent testing for high-impact environments. Record residual risks such as shared-kernel exposure, management-plane compromise or vendor administrator access and match them to workload restrictions.
Key takeaways
- Treat generated actions and content as untrusted even when the user and model are legitimate.
- Separate planning, policy, execution, brokering, artifact release and evidence into distinct boundaries.
- Choose containers, microVMs or VMs through a workload-specific threat and consequence assessment.
- Use one-run identity, default-deny egress, ephemeral storage and no ambient credentials.
- Test escape paths, exfiltration, resource abuse, cleanup and normal usability after material changes.
Frequently asked questions
Is a container an adequate AI agent sandbox?
Sometimes, for bounded lower-risk work with hardening and verified controls. Generated untrusted code, sensitive data or severe escape consequences may justify a stronger virtualized boundary and dedicated capacity. The decision should follow the threat model.
Should sandboxed agents have internet access?
Not by default. Grant a mediated destination and protocol profile only when the task requires it. Browsing arbitrary sites and uploading data are separate capabilities and should not be bundled into one broad network permission.
Can a sandbox replace tool authorization?
No. A sandbox limits runtime effects, while the tool broker must still authorize the initiating subject, target resource and operation. A contained process using an overprivileged business credential can still cause major harm.
Conclusion
A production agent sandbox is a controlled execution service, not an isolated shell bolted onto a chatbot. Its value comes from explicit profiles, strong workload boundaries, brokered authority, constrained networks, ephemeral data, inspected outputs, attributable evidence and teardown that can be proven.
Start with the most powerful agent task and remove every permission it does not need. Draw the run from user authority through broker, runtime, network, storage and artifact release. Each unmediated path is a concrete design decision to fix, test or accept.