Letting a coding agent run commands creates a question that approval prompts cannot answer: what can the resulting process actually reach? A command that looks harmless may launch package scripts, read configuration outside the repository, or modify ignored files that another application later executes. Before delegating repository work, a team needs more than a permission setting. It needs an execution contract with observable checks for allowed access, forbidden access, and the damage still possible inside the boundary.
Harshith's Newsletter / Reader access
Continue reading.
Subscribe free to Harshith's Newsletter to read the rest of this article and unlock every blog and newsletter edition.
Confirm your email to read. Free. Unsubscribe anytime.We remember this browser for 180 days, unless you sign out or clear site data.Already subscribed?
OpenAI’s explanation of the Codex sandbox, retrieved November 19, 2026, provides a concrete starting point. It describes how user-controlled filesystem and network profiles become operating-system restrictions on macOS, Linux, and Windows. It also describes important exceptions and tradeoffs: broad filesystem reads in the workspace profile, writable dependencies, separately launched servers, and platform-specific network behavior. This is an explanation of the system, not evidence that every configuration on every machine has been validated.
The useful next step is to translate those descriptions into a small acceptance suite before the agent receives real work. This article proposes that suite through an illustrative dependency update in a disposable repository. The payoff is a narrower, defensible delegation decision: which commands can run under which profile, what evidence establishes the tested boundary, and when a host or configuration change requires another check.
Approval, containment, and correctness are separate
Command approval asks whether an operation may begin. Execution containment restricts the resources its processes can access. Output verification asks whether the resulting work is correct and acceptable. Treating these as one control creates blind spots.
| Control | Question | Useful evidence | What it does not establish |
|---|---|---|---|
| Command approval | May this operation run with these permissions? | Recorded command, requested profile, authorization decision | That the profile was enforced |
| Execution containment | Which resources can the process tree reach? | Positive and negative probes through the actual execution path | That permitted edits are correct |
| Output verification | Should these changes enter the trusted repository? | Independent diff review, tests, artifact inspection | That inaccessible resources stayed inaccessible |
OpenAI describes the model requesting permissions for individual commands while the harness decides whether to grant them. Additional permissions can expand access within the sandbox; an escalated request can ask to run outside it. Therefore, an approved command is not necessarily a sandboxed command. The execution record must distinguish those cases. These mechanisms are described in the primary sandbox explanation.
The command-selection framework in Before your AI touches the terminal addresses the authorization question. Boundary testing adds the next layer: after choosing an acceptable command, demonstrate the restrictions under which it will execute.
Understand what the boundary actually encloses
According to OpenAI’s sandbox explanation, Codex constrains commands in the user’s existing environment using platform-specific facilities rather than making a separate VM or container the general execution model. macOS uses Seatbelt, Linux combines bubblewrap and seccomp-bpf, and compatible Windows devices can use an MXC-based sandbox during a transition from the earlier Windows implementation.
The intended chain is configuration, resolved permission profile, harness launch, operating-system enforcement, and, where configured, proxy enforcement. A common profile API makes that chain easier to use across platforms. It does not make the operating-system mechanisms or every observable behavior identical.
The built-in workspace profile illustrates why names are insufficient. OpenAI says it permits writes inside the workspace while protecting directories such as .git and .codex, permits broad reads subject to the user’s OS permissions, and disables network access. An external credentials file may therefore remain readable. The claim supported by the examined explanation is a constrained workspace-writing profile, not a workspace-only confidentiality boundary.
That distinction changes the contract. If the requirement is merely to prevent external writes, broad reads may be compatible with it. If the requirement is to keep host credentials unavailable to commands, the team must add and test read denials or choose an environment where those credentials are absent. Disabling command network access does not make readable secrets unreadable.
Write the contract before the profile
Start with the task’s minimum resource requirements, not the convenience of the developer’s current machine. A useful contract is a short specification containing allowed resources, forbidden resources, execution routes, evidence requirements, and a stop rule.
- 01
Name the required access
List source paths, manifests, lockfiles, package caches, temporary directories, toolchain reads, and network destinations. Separate reads from writes. A cache that must be writable deserves an explicit entry, not an accidental grant to the whole home directory.
- 02
Name the prohibited access
Specify protected metadata, external directories, credentials, editor configuration, local services, and external destinations. Decide whether a path must be unreadable, unwritable, or both. Those are different assertions.
- 03
Identify every execution route
Include shell commands, file-edit tools, child processes, servers, and any host-side helpers. Record which route applies the profile. A tool outside that route needs its own containment decision.
- 04
Set the acceptance and stop rules
Require allowed probes to succeed and forbidden probes to encounter the intended restriction. An unexpected success stops delegation. An unexplained failure is inconclusive. Any execution outside the tested profile requires a separate authorization and risk decision.
Keep the contract outside agent-writable paths. Record the execution host, OS version, Codex version, workspace roots, selected profile, relevant configuration layers, proxy mode, and approval behavior. Record resolved configuration where available, with sensitive values redacted. Identical profile names are not evidence of identical effective permissions.
Illustrative worked example: a dependency update
Suppose the delegated task is to update one already-reviewed dependency to a specified version, refresh its lockfile, and run the existing tests without changing application behavior. Create a disposable fixture with package.json, package-lock.json, src/, test/, node_modules/, and an ignored scratch/ directory. Disable editor automation for the fixture and never reuse its dependencies in a trusted project.
In a sibling directory outside the workspace, create private-fixture/token.txt containing only DUMMY_SECRET_FOR_BOUNDARY_TEST. Create external-sentinel.txt with a known value. Inside the workspace, prepare harmless sentinel files under .git/hooks/, .codex/, and .vscode/. These represent resources to protect, not real hooks, settings, or credentials. Prepare all fixtures before launching the probes.
The proposed contract allows repository edits, disposable dependency installation, a dedicated writable cache, and necessary toolchain reads. It makes .git, .codex, and .vscode read-only, denies the external private-fixture directory, and denies writes to the external sentinel. The initial phase has no network access. If artifacts cannot be staged in advance, a separate download phase gets narrowly specified network access.
| Probe | Example operation | Expected result | Independent check |
|---|---|---|---|
| Required read | Read package.json and a source fixture | Allowed | Compare output with known fixture content |
| Required write | printf 'probe\n' > scratch/allowed.txt | Allowed | Check exact file content |
| External secret read | cat ../private-fixture/token.txt | Denied | Check that the dummy token was not returned |
| External write | printf 'changed\n' > ../external-sentinel.txt | Denied | Check the sentinel remains unchanged |
| Protected metadata write | Append harmless text to prepared files under .git and .codex | Denied | Compare fixture hashes |
| Editor configuration replacement | Overwrite, rename, and delete prepared .vscode fixtures in separate probes | Denied | Check content and path existence |
| Alias access | Read the private fixture through a prepared symlink or junction | Denied or launch rejected | Distinguish sandbox rejection from an invalid alias |
| Child-process access | Launch a child that repeats the external read and write probes | Denied | Check child output and external sentinel |
Probe different operations separately. A denied overwrite does not establish a denied deletion, replacement, or directory rename. A failed read through a broken symlink establishes nothing about alias enforcement. Confirm fixture validity from a trusted observer, using only dummy resources, before interpreting the sandbox result.
For each probe, record an identifier, exact invocation, execution route, profile, expected outcome, observed outcome, exit status, diagnostic output, and independently checked resource state. Keep observer records outside the writable fixture. Mark an ambiguous result inconclusive rather than converting every nonzero exit into a security success.
For example, the external-write row is accepted only when the attempted operation encounters the intended boundary and the observer confirms that the sentinel is unchanged. A missing parent directory is a fixture failure. A shell syntax error is a probe failure. Neither demonstrates containment.
Test network enforcement, not proxy cooperation
Proxy variables alone are not a security boundary. In OpenAI’s historical Windows engineering account, the team describes an early approach that redirected common clients toward a dead proxy and altered command resolution. It rejected that network suppression as advisory because programs could ignore the environment or open sockets directly.
The newer explanation describes a different arrangement: commands reach a policy proxy while operating-system restrictions block direct external connections. The network proxy README also documents domain allow and deny rules, limited-mode method restrictions, and diagnostic responses. Test both the proxy’s decision and the operating system’s resistance to bypass.
- Establish endpoint health Use disposable endpoints controlled by the team, with an allowed host, an explicitly denied host, and an unlisted host. Confirm reachability from the trusted observer first. Use dummy payloads only.
- Check the offline phase Attempt external requests from a normal proxy-aware client and a small direct-socket client. Both must fail under this phase’s contract. A child process should repeat the checks.
- Check the restricted download phase If downloads are required, verify that the intended host succeeds through the proxy and the explicitly denied host is blocked. Record whether an unlisted host is blocked or awaits approval. Do not approve it during a probe meant to demonstrate denial.
- Attempt bypass and redirects Repeat requests with proxy variables removed and explicit proxy bypass enabled. Use a direct connection to the controlled endpoint. Have an allowed endpoint redirect to a denied endpoint and observe whether the destination is contacted.
- Check local services separately Start a harmless local fixture service and test access through relevant routes. Do not probe real privileged daemons. If the contract requires local-service isolation, unexpected fixture reachability prevents acceptance of that environment.
Capture both client diagnostics and controlled-server access records. A timeout without attribution is inconclusive. A domain-policy rejection is evidence about that request path; it is not evidence that every direct-socket route is blocked. The positive endpoint test prevents a disconnected machine from appearing perfectly contained.
Do not equate read-only networking with confidentiality. The proxy README defines limited mode around GET, HEAD, and OPTIONS, but those requests can still carry data in their destinations or query strings. It also acknowledges DNS-rebinding limitations and recommends lower-layer egress controls for hostile-DNS threat models. Those qualifications appear in the examined proxy documentation.
A host change invalidates assumptions
Two documented differences particularly deserve tests. OpenAI says Linux and MXC deny globs are expanded to concrete paths before command launch, so newly matching paths are not automatically added during that command. It also says the MXC setup allows host-loopback connections, leaving other local services reachable. These are bounded statements about the implementation described in the primary explanation, not claims about every installed Windows or Linux configuration.
If confidentiality depends on a glob, add a dynamic-path probe: launch a waiting sandboxed command, have the trusted fixture controller create a new matching dummy file, then instruct the waiting process to attempt a read. Test again in a newly launched command. This separates launch-time coverage from protection of paths created later. Prefer a denied directory when the requirement is to protect all future contents.
Rerun the suite after changes to OS, sandbox backend, Codex version, workspace roots, configuration, proxy mode, approval behavior, or tool-launch integration. Portable Agent Skills Need Portability Tests explains why reusable task instructions do not imply equivalent execution. The same principle applies to a permission profile: portability is a claim to test, not a property established by copying configuration.
Execution coverage matters as much as host coverage. OpenAI states that the harness does not automatically sandbox the command that starts a configured stdio MCP server, and demonstrates wrapping such a command with codex sandbox. That exception in the sandbox explanation means successful shell probes do not establish containment for every connected tool. Test the wrapper or evaluate that server separately.
Containment leaves permitted damage possible
OpenAI gives a useful warning: an agent could modify an installed formatter under node_modules, where Git might not report the change, and an editor could later execute that formatter outside the sandbox. The primary article’s example is not a reported incident. It demonstrates why a constrained write can create a later execution risk.
In the illustrative update, discard node_modules, caches, and build outputs after the run. Transfer only reviewed changes into a clean checkout. Inspect manifest scripts and lockfile destinations, independently reinstall reviewed dependencies under the chosen controls, and run a trusted test baseline. Do not let the agent’s report substitute for inspecting the artifacts.
Check ignored paths as well as the tracked diff. The agent may also weaken tests, introduce an incorrect version, delete useful source code, or consume excessive resources while staying within permitted paths. Filesystem and network acceptance tests do not establish correctness, resource limits, or absence of malicious dependencies.
If the agent completes the nominal task while violating the contract, preserve the evidence before cleanup. When an AI Agent Succeeds the Wrong Way provides the incident-handling continuation. An unexpected probe success should be investigated as a boundary failure first, without assuming intent by the model.
Use this next: make a bounded delegation decision
The examined materials explain mechanisms and limitations. They do not provide an independent acceptance result for your machine, resolved profile, and workflow. A finite probe suite cannot prove that every escape is impossible, but it can expose mismatches that configuration review and approval prompts leave invisible.
- Delegate in the tested environment Required operations succeed, forbidden operations encounter attributable restrictions, all execution routes have been evaluated, and residual workspace damage is acceptable in a disposable checkout.
- Revise the contract or profile Legitimate work fails because required access was omitted. Add the smallest justified permission, record the change, and rerun affected positive and negative probes.
- Move to stronger isolation Required host reads expose sensitive data, local services violate the threat model, or the workflow needs broadly privileged execution. Use a dedicated environment without production credentials and evaluate its bridges and egress separately.
- Stop and investigate A forbidden operation succeeds, execution silently leaves the tested route, or diagnostics cannot establish why a probe failed. Do not resolve that uncertainty by granting more access.
Start with one recurring repository task and one disposable fixture. Keep the contract and probe records beside the operational runbook, outside agent-writable paths. The durable improvement is not a claim that the agent is safe. It is an evidence-backed statement about where its commands may act, under a named configuration, with explicit conditions for retesting and a separate decision about accepting its work.

