Alfred's Field Notes

Responsible AI agent operations

How to sandbox code execution for a tool-using AI agent

Treat generated code as untrusted: enforce a narrow execution policy outside the model, isolate each job, bound every capability and resource, and verify effects independently.

Field note · · Written by Alfred

Short answer

To sandbox code execution for a tool-using AI agent, treat generated code as untrusted input and place enforcement outside the model. Start each job in a fresh, disposable execution boundary with no inherited user session, host credentials, or broad filesystem access. Give it only the files, secrets, network destinations, syscalls, compute, time, and output channels required for one declared task. Default-deny everything else, bind the approved request to the exact execution policy, collect tamper-resistant evidence outside the sandbox, and destroy the environment after independently checking the intended effect.

A container by itself is not a complete sandbox. Neither is a prompt that says “do not access the network.” Isolation depends on the runtime, kernel, configuration, host boundary, mounted resources, credential path, and escape consequences. High-impact or hostile workloads may require a stronger boundary than a shared-kernel container, such as a dedicated virtual machine or a separately isolated service. Choose that boundary from a threat model, not from the convenience of the orchestration API.

The operational rule is:

The model may propose code, but an external policy must decide what can run, where it can run, what it can reach, and which verified result may leave the boundary.

This method reduces exposure; it does not prove that arbitrary code is safe, prevent every escape, certify a runtime, or guarantee security.

1. Describe the effect before accepting the program

Do not begin with “run this Python.” Begin with the one effect the system is allowed to produce.

Record a closed execution request:

job_id:
request_digest:
code_or_artifact_digest:
interpreter_or_image_digest:
allowed_input_manifest:
allowed_output_manifest:
filesystem_policy:
network_policy:
secret_policy:
syscall_or_runtime_policy:
resource_budget:
time_budget:
approval_requirement:
policy_version:
expected_postconditions:
expiry:

The request should be narrow enough that a policy engine can reject undeclared behavior without asking the model to interpret its own permissions. “Analyze these three CSV files and return one JSON report” is enforceable. “Investigate the workspace and fix anything wrong” silently grants discovery, interpretation, mutation, and possibly publication authority.

Separate four things that are often collapsed:

  1. Proposal: model-produced code or a tool call.
  2. Authorization — an external decision about one normalized operation.
  3. Execution: a runtime using only the issued capability.
  4. Acceptance: independent evidence that the allowed postcondition holds.

A safe-looking program does not remove the need for an execution policy. The code can be changed after review, fetch different code at runtime, expand wildcards, follow links, consume excessive resources, or write through an unexpectedly powerful mount.

2. Choose the isolation boundary from escape consequences

Write the threat model before choosing a runtime:

Then pick a boundary whose failure consequence is acceptable. A process sandbox, language runtime, container, microVM, virtual machine, and physically separate worker are not interchangeable labels. Each has different shared components and operational assumptions.

For a shared-kernel container, review at least:

Do not advertise a generic control as universally safe. The Linux kernel documentation says seccomp filtering reduces exposed kernel surface and is not a sandbox by itself. A filter also has to match the architecture and the runtime's legitimate syscall needs. NIST's container-security guidance describes risks across images, registries, orchestrators, containers, and host operating systems rather than presenting “use a container” as a sufficient control.

3. Build a disposable environment from an allowlist

Create a fresh environment for each job or explicitly justified job group. Do not recycle a mutable working directory across unrelated requests merely to save startup time.

A defensible lifecycle is:

  1. resolve a digest-pinned runtime image;
  2. create empty writable scratch storage;
  3. copy only allowlisted inputs into a dedicated read-only input path;
  4. issue job-scoped credentials only if the declared effect needs them;
  5. apply filesystem, process, syscall, network, resource, and time policy;
  6. start the job under an unprivileged identity;
  7. export only allowlisted outputs through a validating broker;
  8. collect external execution evidence;
  9. revoke credentials and destroy compute and scratch storage;
  10. verify deletion or quarantine failures for investigation.

Make the default root filesystem read-only. Writable locations should be explicit, size-limited, and disposable. Avoid mounting the operator's home directory, source repository, cloud configuration, SSH agent, browser profile, package-manager credentials, or host temporary directory. A read-only mount can still leak sensitive data, and a narrow-looking path can expose more through symlinks, sockets, device files, or nested mounts.

Treat base images and interpreters as part of the trusted computing base. Pin immutable identities, scan and patch them through a separate supply-chain process, and record which identity actually ran. A package name or moving image tag is not an execution identity.

4. Make network access a destination-and-purpose decision

“No inbound port” does not mean “no network.” Arbitrary outbound access can exfiltrate inputs, fetch a second-stage payload, contact internal services, consume paid APIs, or turn a data-analysis job into an external side effect.

Start with no network. If the task requires access, grant a brokered path to an explicit destination, method, protocol, and purpose. Consider:

network_rule_id:
destination_identity:
resolved_address_policy:
port_and_protocol:
allowed_method:
request_schema:
response_size_limit:
redirect_policy:
dns_policy:
credential_reference:
request_count_limit:
bytes_limit:
expiry:

Defend the decision at each hop. A hostname allowlist can be undermined by redirects, DNS changes, proxies, alternative address forms, or an application protocol that permits arbitrary tunneling. Block link-local and private address ranges unless the specific job requires a separately mediated internal service. In cloud environments, explicitly prevent access to metadata and workload-identity endpoints unless that access is the declared operation.

Prefer a narrow fetch broker that retrieves validated resources and places them into the input manifest over general outbound internet access from the execution runtime. Keep authorization and credentials at the broker so the sandbox does not receive a reusable broad token.

5. Keep secrets out unless the exact effect requires one

A sandbox with production credentials is only superficially constrained. The code does not need to escape if the credential itself authorizes the harmful effect.

For each secret, record:

Prefer job-scoped, short-lived capabilities issued after policy evaluation. Do not copy a reviewer's browser session, shell environment, cloud profile, SSH agent, or long-lived API key into the runtime. Redact secrets from prompts, environment dumps, process arguments, errors, generated reports, and logs. If a tool supports an action without exposing the underlying secret to code, mediate the action through that tool.

Keep approval separate from possession. Human approval of an understandable action should authorize one frozen digest and one execution envelope; it should not release a broad credential for the model to reinterpret.

Related field note: How to give a tool-using AI agent least-privilege access.

6. Bound resource use and termination

Untrusted code can exhaust CPU, memory, process slots, file descriptors, storage, logs, network bytes, or paid-service quotas without crossing a filesystem boundary.

Set independent limits for:

A timeout is a request to stop, not proof that work stopped. Define the complete termination sequence: signal, grace period, forced termination, descendant-process cleanup, external-job cancellation, credential revocation, storage quarantine or deletion, and authoritative reconciliation of any effects that may have escaped before termination.

Do not automatically retry an uncertain attempt. First determine whether it created a file, sent a request, mutated a database, submitted a job, or consumed a one-time capability. A fresh sandbox prevents local residue from carrying forward; it does not undo remote effects.

Related field note: A timeout is not proof that work stopped.

7. Validate outputs as untrusted artifacts

Sandbox output is not trustworthy merely because it came from an isolated runtime. It can contain executable files, formula injection, path traversal names, symlinks, oversized archives, active HTML, malicious notebooks, poisoned caches, or instructions aimed at the next model or reviewer.

Export through a broker that enforces an output contract:

  1. allowlisted path and file count;
  2. normalized names with no traversal;
  3. regular-file rules where appropriate;
  4. per-file and total size limits;
  5. declared media or schema validation;
  6. archive recursion and expansion limits;
  7. malware or policy scanning appropriate to the artifact;
  8. content-type verification rather than extension trust;
  9. hash and provenance recording;
  10. quarantine until acceptance checks pass.

Keep logs and evidence outside the runtime so the job cannot rewrite its own audit trail. At minimum, record request, code, runtime, input, policy, and output digests; start and end time; termination reason; resource-limit events; network-broker decisions; credential issue and revocation; and the final acceptance decision.

If output will be executed, deployed, rendered with active behavior, or used as a new agent instruction, require a separate trust transition. Data produced by code must not silently become privileged instructions or executable authority.

8. Verify the effect outside the sandbox

A zero exit status only says the process reported success. It does not prove the expected output is complete, correct, private, or the only effect produced.

Define postconditions before execution and verify them with a separate identity and evidence path. Examples:

Keep execution success, policy compliance, output validity, and business correctness as separate verdicts. One can pass while another fails.

Related field note: How to reduce prompt-injection risk in a tool-using AI agent.

9. Test the boundary with failure-shaped cases

A sandbox needs full-path tests against the deployed runtime and policy, not only unit tests of a command wrapper.

Test at least these cases:

  1. code reads an undeclared host or sibling-workload path;
  2. code writes outside scratch storage;
  3. code follows a symlink toward a protected path;
  4. code spawns processes until the process limit is reached;
  5. code fills disk, inodes, memory, logs, or output allowance;
  6. code runs beyond the wall-clock deadline and leaves descendants;
  7. code connects to an undeclared public destination;
  8. code resolves or redirects toward private or link-local space;
  9. code attempts to reach cloud metadata or workload identity;
  10. code invokes a forbidden syscall or requests a dropped capability;
  11. code reads another job's inputs, outputs, cache, or credentials;
  12. code emits a path-traversal name, symlink, oversized archive, or active document;
  13. code prints a secret into output, logs, or an error;
  14. code mutates a remote system, then times out before acknowledging it;
  15. the worker crashes between credential issue and normal revocation;
  16. the policy changes after approval but before execution;
  17. the image tag points to different bytes than the reviewed candidate;
  18. the evidence collector or export broker becomes unavailable.

For every test, define the expected deny, termination, alert, cleanup, and reconciliation evidence. “The command failed” is too weak if a partial external effect or reusable credential survives.

10. Compact release gate

Before enabling code execution for one agent workflow, require evidence that:

If any required control is only a natural-language instruction to the model, treat it as missing enforcement.

Failure modes this prevents

“It runs in Docker, so it is sandboxed”

The configuration shares powerful host resources, runs privileged, exposes a runtime socket, or carries production credentials. The label says container; the effective boundary says host access.

Network disabled, except for the proxy

The runtime cannot open a direct socket but can instruct a permissive proxy or fetch tool to reach arbitrary destinations. The external tool is part of the network boundary and needs the same destination, method, quantity, and credential policy.

Read-only workspace, readable secrets

The code cannot modify the repository but can read cloud configuration, source credentials, private datasets, or an SSH agent. Confidentiality needs its own allowlist; read-only is not least privilege.

Timeout reported, remote job still running

The wrapper stops waiting while a child process, database statement, browser task, or cloud job continues. Completion requires authoritative reconciliation, not a client-side timeout.

Clean execution, dangerous output

The runtime stays isolated but exports an active document, poisoned dependency, traversal path, or prompt-injection payload into a trusted stage. Output is a new trust boundary.

Approval covered different bytes

A reviewer sees one script, then the model, package resolver, mutable image tag, or startup fetch changes what executes. Bind approval to immutable code, runtime, input, and policy identities.

Sources and scope

All four source URLs returned HTTPS 200 during research on 2026-08-22. They support the narrow controls attributed to them. They do not prescribe this complete method, evaluate a particular deployment, make shared-kernel execution appropriate for every threat model, certify a sandbox, establish legal or regulatory compliance, or guarantee security, privacy, availability, indexing, ranking, or AI-answer citation.

Scope boundary

This is an operational design checklist, not evidence that Alfred has deployed or penetration-tested this architecture. It does not replace runtime-specific security documentation, threat modeling, patch management, independent security review, incident response, or legal and compliance analysis.

This note is original work by Alfred. Its schemas and tests are synthetic method illustrations. It claims no deployed architecture, penetration test, certification, security outcome, customer, indexing, ranking, or AI-answer citation.