A Practical Sandbox Architecture for Internal AI Agents That Can

An AI agent sandbox architecture should treat the model as a planner that proposes actions through controlled systems, rather than as a privileged identity with a shell and standing access to internal infrastructure. The goal is practical: let an agent inspect selected code, run an approved test, prepare a patch, or invoke a narrowly defined workflow while limiting the impact of a mistaken request, unsafe model output, or hostile repository content.

The central rule is to separate reasoning, authorization, execution, credentials, data access, and evidence. When those responsibilities sit in one long-running process with broad credentials, an inappropriate tool request can reach valuable systems directly. When each responsibility has its own control boundary, the same request can be denied before execution or contained in a disposable environment.

Start With Separate Trust Zones

A useful internal agent does not need standing access to every system it may discuss. It needs a constrained path for specific approved actions. A practical design separates at least five zones.

Zone	Responsibility	What it must not control	Typical control
Reasoning service	Interprets a request and proposes a plan	Cloud credentials, direct production access, host filesystems	Structured tool calls and bounded context
Policy gateway	Checks proposed actions against deterministic rules	Model-selected authorization decisions	Allowlists, schemas, and approval checks
Execution sandbox	Runs code, CLIs, builds, or workflow steps	Host control-plane access and durable secrets	Ephemeral isolation, resource limits, non-root execution
Credential broker	Issues access for an approved action	Free-form export of credentials to the model or shell	Narrow, short-lived tokens
Evidence plane	Records requests, decisions, inputs, outputs, and approvals	Agent-controlled alteration of audit records	Centralized audit storage

This separation responds directly to recognized LLM application risks. OWASP identifies excessive agency and insecure output handling among the risks that require controls such as least privilege, output validation, and sandboxing around runtime actions. OWASP Top 10 for Large Language Model Applications

Use a Plan, Check, Mint, Execute, Record Flow

The model should never be the final authority for a tool call. It may propose an operation such as run_maven_tests, create_branch, or invoke_workflow. A policy gateway then evaluates that request independently, using the caller, target, environment, action type, and approval state.

Keep reasoning separate from credentials

The reasoning service should receive task context, tool descriptions, policy feedback, and bounded results. It should not receive cloud access keys, database passwords, broad Git tokens, or administrator sessions for an automation platform.

For Java and React teams, this can mean retrieving a selected repository snapshot or file set through a repository service instead of mounting every repository into the model-serving environment. Apply the same care to command output. Before it is returned to the model, screen logs and artifacts for sensitive material that tools may print accidentally.

Expose typed capabilities instead of general shell access

A generic shell(command) tool creates a broad and difficult-to-review authority boundary. Where possible, expose task-specific capabilities with validated inputs, such as run_gradle_test(module, test_selector), create_branch(repository, base_ref), or invoke_workflow(workflow_id, payload).

Each capability should define the target scope, expected input shape, maximum runtime, output limit, permitted network destinations, and approval requirement. The model may select from this catalog, but it cannot expand the catalog through a prompt. This makes authorization more reviewable and reduces the chance that free-form arguments turn into unintended commands.

Make policy deterministic and external to the model

The policy gateway should decide whether a proposed action is allowed without relying on the model’s confidence, explanation, or wording. Its checks can include:

• Whether the capability is enabled for the requesting team and environment.
• Whether the repository, namespace, workflow, account, or resource is explicitly in scope.
• Whether the action mutates state, sends information externally, or accesses sensitive data.
• Whether an applicable human approval exists.
• Whether the credential broker can issue access limited to the requested action.

Return denials as concise structured results, such as target_not_allowlisted or production_requires_approval. This lets the agent revise its plan without treating policy as a conversational instruction that it can reinterpret.

Run Work in Disposable Sandboxes

Agent-assisted coding and automation often require execution. That execution should begin in a clean environment and end with teardown. Create a new sandbox for each job, attach only needed inputs, apply resource limits, collect declared artifacts, and destroy the environment when the job finishes. A long-lived workspace can retain credentials, modified configuration, or untrusted files from an earlier task.

The isolation boundary should match the workload’s risk. gVisor provides container-level isolation by intercepting Linux system calls in a user-space application kernel called Sentry, reducing host-kernel exposure for code running inside the sandbox. gVisor documentation Firecracker uses Linux KVM hardware virtualization for lightweight microVMs, and its Jailer uses controls including seccomp filters, cgroups, and Linux namespaces. Firecracker MicroVM documentation

For code that is generated by an agent, comes from an untrusted repository, or invokes package tooling, a microVM can provide a useful stronger isolation boundary. For a predefined, tightly bounded task with read-only inputs, a constrained container runtime may fit operational needs. In either case, isolation does not replace scoped credentials, egress restrictions, or validation before side effects occur.

Make Credentials Per-Action

A sandbox with a production administrator token still has a large blast radius. The credential broker should issue access only after policy approval and only for the specific resource and action the job requires.

Use a workload identity or brokered session where the platform supports it, rather than placing reusable secrets in environment variables. A token that can read one repository branch is materially different from a token that can change organization settings. A token that can prepare a draft pull request is different from one that can merge into a default branch.

Record the requested scope, token lifetime, audience, target, and policy decision with the action. For cloud automation, distinguish read, propose, and execute capabilities. Read retrieves bounded information. Propose creates a plan or preview. Execute performs a state-changing operation and should use a higher approval requirement for consequential environments. This keeps a conversational request from silently becoming an operational change.

Constrain Files, Network Egress, and Outputs

Filesystem access should use declared inputs and outputs. Mount a checked-out repository or sanitized archive read-only when a task only analyzes or tests code. When a build requires writes, use a job-local working directory and export only named artifacts such as test reports, patches, or generated documentation. Host filesystems, developer home directories, CI configuration, and shared build caches should remain unavailable unless a specific capability requires them.

Apply the same specificity to network access. Deny outbound access by default, then allow only the destinations needed for the capability. A dependency installation may need an approved package proxy; it does not need unrestricted internet egress. A workflow invocation may need an internal endpoint; it does not need access to unrelated database networks. Log allowed destinations and policy decisions while avoiding indiscriminate storage of sensitive request payloads.

n8n documents an external-container Task Runner approach for custom code. Its hardening guidance includes explicit environment-variable allowlists, non-root execution, read-only filesystems, and container controls through AppArmor. n8n Task Runner security guidance The same design principle applies to automation credentials: give a task a limited reference or brokered token, not access to an entire credential store.

Use an Action Envelope for Reviewable Jobs

Before a tool call reaches an executor, create an integrity-protected action envelope. This is an implementation pattern for carrying the authorized job definition from the policy gateway to the sandbox. It is not another prompt for the model.

• Intent: the requested outcome and selected capability.
• Scope: the repository, branch, environment, workflow, account, or resource identifier.
• Inputs: validated arguments, approved file references, and data classification.
• Authority: policy version, caller identity, approval identity, and credential claims.
• Limits: runtime, CPU, memory, disk, network destinations, and output quota.
• Evidence: correlation ID, timestamps, decision results, artifact references, and final status.

The executor accepts work only when the envelope is valid and runs only the parameters it contains. This prevents a later model message from expanding an approved task such as testing one module into a different operation after authorization is complete.

Roll Out Controls Alongside Useful Work

Start with workflows that are useful and recoverable: codebase questions over sanitized source, isolated test execution, issue classification, and draft pull-request creation. Keep production writes, customer-data access, security configuration changes, and external communications behind a higher approval tier while the team validates its controls in internal use.

Implementation Checklist

• Inventory each agent tool, its inputs, mutation capability, target systems, and credentials.
• Replace broad shell access with typed capabilities where feasible.
• Validate schema, caller, target, environment, and approval status in a policy gateway outside the model.
• Create ephemeral sandboxes with non-root users, restricted mounts, resource limits, and automatic teardown.
• Default network egress to deny and add destination allowlists per capability.
• Issue short-lived credentials with the narrowest practical action and resource scope.
• Store authorization decisions and job evidence outside agent control.
• Require human review for production changes, destructive actions, sensitive-data access, and external communications.
• Exercise denied egress, expired credentials, invalid inputs, sandbox failures, and rejected approvals before expanding access.
• Review capabilities as repositories, workflows, and ownership change.

Measure the rollout through evidence. Teams should be able to identify which tool ran, who requested it, why policy allowed it, what scope it received, which artifacts it produced, and whether a person approved the side effect. If answering those questions requires reconstructing an agent conversation after the fact, the controls are incomplete for high-impact automation.

FAQ

Do internal AI agents need sandboxing if only employees use them?

Yes. Employee access does not eliminate the risks of unsafe tool requests, compromised source content, over-broad credentials, accidental misuse, or software defects. Internal identity is an authorization input, not a substitute for isolation and least privilege.

Should every task run in a microVM?

Not necessarily. Use an isolation boundary that reflects the risk of the workload. Generated or untrusted code generally needs a stronger boundary than an API-only task with no shell, filesystem, or arbitrary-code capability. Pair that decision with scoped credentials and egress controls.

Can a sandbox access production?

A sandbox can receive narrowly scoped, short-lived production access for an approved operation, but it should not hold standing administrative credentials. Separate observation from mutation, validate targets deterministically, and require additional approval for consequential changes.

What should be implemented first?

Remove broad, long-lived credentials from the agent and place tool calls behind a deterministic policy gateway. This establishes a control point for credential brokering, sandboxing, network restrictions, approvals, and audit evidence.

Sources

• OWASP Top 10 for Large Language Model Applications
• gVisor Documentation
• Firecracker MicroVM Documentation
• n8n Task Runners Documentation

Editorial note: AI assisted with research and drafting. Sources were selected for verification.