The useful thing about a coding-agent sandbox is not that it sounds secure. It is that it can make the working set explicit. If an agent needs a repository, a task brief, a fixture folder, a mounted bucket, or a place to write artifacts, I want those decisions in one manifest instead of scattered across prompts, shell wrappers, and tribal memory.
OpenAI's recent Agents SDK changelog makes that direction clearer. Sandbox Agents arrived as a beta surface around SandboxAgent, Manifest, SandboxRunConfig, workspace entries, mounts, snapshots, and memory. Later releases tightened local source materialization, added provider-backed sandbox details, and hardened diagnostics around sensitive payloads. That is a good reminder for production teams: a sandbox is only as disciplined as the contract used to hydrate it.
The contract I would review
I would treat a sandbox manifest like a small deployment spec. It should answer five questions before the agent gets a token of autonomy.
| Question | Manifest decision |
|---|---|
| What files exist at start? | Synthetic files, copied local directories, cloned repos, or mounts |
| What host paths are trusted? | Explicit path grants, usually read-only |
| Where can output land? | A named workspace directory or mounted destination |
| What state survives? | Snapshot and memory policy |
| What gets traced? | Workflow, group, metadata, and sensitive-data policy |
That sounds formal, but the implementation should stay boring. The point is not a new platform abstraction. The point is one reviewable object that limits what the agent can see and explains why.
Keep local sources inside the base directory
The most practical recent change is the Agents SDK 0.17.0 local source boundary. LocalFile.src and LocalDir.src now stay within the materialization base directory unless covered by Manifest.extra_path_grants. Relative sources resolve from the SDK process working directory. Absolute sources need to already be inside that boundary or under an explicit grant.
That is exactly the right failure mode. If a production agent suddenly needs /opt/shared-docs, /tmp/build-output, or a generated skill bundle outside the app root, the manifest should say so. A prompt should not be able to smuggle that path into the workspace.
My default shape is this:
from pathlib import Path
from agents.sandbox import Manifest, SandboxPathGrant
from agents.sandbox.entries import Dir, LocalDir
TRUSTED_DOCS = Path('/opt/company/agent-docs')
manifest = Manifest(
extra_path_grants=(
SandboxPathGrant(path=str(TRUSTED_DOCS), read_only=True),
),
entries={
'repo': LocalDir(src=Path('repo')),
'docs': LocalDir(src=TRUSTED_DOCS),
'output': Dir(),
},
)
The useful review question is simple: would I be comfortable putting every granted host path in a pull request description? If not, the grant is probably too broad.
Separate workspace permissions from model permissions
A sandbox manifest is not the same thing as tool approval. File permissions decide what materialized files can be read, written, or executed by sandbox users. Tool approval decides whether the agent may call a capability. API credentials decide what remote systems can be touched. Mixing those three creates fake confidence.
I would keep the split visible in review:
- Workspace entries should be the minimum input set.
- Host path grants should be read-only unless the agent must write back.
- Secrets should use ephemeral environment entries or the hosting provider's secret path, not persisted workspace state.
- Shell and filesystem capabilities should match the task, not the agent brand.
- Human approvals should cover irreversible actions, external side effects, and permission escalations.
This pairs naturally with the approval boundaries I wrote about in human handoff gates for long-running AI agents. The sandbox answers what the agent can touch. The handoff gate answers when a person must take responsibility.
Snapshots are not memory
The sandbox docs distinguish workspace state from agent memory, and that distinction matters. A snapshot can restore files. Memory can carry lessons between runs. Those are different risk profiles.
For coding agents, I want snapshots for reproducibility and memory for durable operating notes, but I do not want either one to become an unreviewed junk drawer. A good rule is to snapshot outputs needed to resume or audit the task, then write memory only for reusable lessons that would survive a repo checkout or a new worktree.
That keeps the state budget small. It also keeps the next run from inheriting stale context that should have been deleted with the branch. This is the same pressure behind a state budget for production AI agents: persistence helps only when the retained state has a named owner and a reason to survive.
Trace the manifest, not just the model call
Tracing that captures model generations, tool calls, handoffs, guardrails, and custom events is useful, but I would add one more habit: record the manifest identity with the trace. Not necessarily the full manifest if it contains sensitive paths or environment metadata. A hash, version, or review link is usually enough.
When an agent changes a file it should not have seen, the first debugging question is not model quality. It is hydration. What repo was copied? Which path grants were active? Which mount strategy was used? Was the run resumed from a stale snapshot? Did a retry preserve session history?
The current SDK direction is already pushing teams this way. Release notes mention safer diagnostic logging, sandbox-aware tracing, mounts, snapshots, and source-boundary checks. Claude Code's changelog shows a similar operational trend around permission prompts, retry controls, memory limits, MCP command ergonomics, and review behavior. The common theme is that agent systems are becoming operational software, not chat transcripts with tools attached.
My minimum launch gate
Before I let a coding-agent sandbox run unattended on production-adjacent work, I would ask for this packet:
- A manifest diff or generated manifest preview.
- A list of host path grants, each with owner, reason, and read/write mode.
- A secret handling statement that says what is ephemeral and what persists.
- A snapshot policy, including retention and restore trigger.
- A trace pointer that ties the run to the manifest version.
- One deny-path smoke test, such as trying to copy a sibling directory that should be outside the base.
That last test is small, but it catches the right class of mistake. If the sandbox cannot prove what it refuses, I do not trust what it permits.
The next useful wave of coding-agent infrastructure will not be louder autonomy. It will be manifests, traces, path grants, memory files, and approvals that are plain enough for a tired engineer to review before merge.