The most interesting architectural decision in OpenAI Codex is not the model … it is where the model runs.

Most AI coding tools, Claude Code, Gemini CLI, Copilot, run on your machine.

They read your files, edit your code and execute commands in your terminal.

The trust boundary is your laptop, to a large degree.

If the model decides to run rm -rf /, the only thing between you and disaster is a permission prompt … in principle.

Codex takes a different approach.

It puts the agent inside a sandbox.

The sandbox constrains where the agent can operate, what files it can touch and what commands it can run… not through prompts or guidelines, but through technical enforcement at the operating system level.

This is the shift from tool-based agents to environment-based agents.

Instead of giving the model a set of tools to call, you give it a bounded environment to live in.

The core idea

Sandboxing is the boundary that lets Codex act autonomously without giving it unrestricted access to your machine.

That sentence contains the entire philosophy.

Autonomy requires boundaries.

The more you want an agent to do on its own, without asking you for permission every ten seconds, the tighter the environment needs to be.

Paradoxically, more constraint enables more freedom.

Think about it from the user’s perspective.

If the agent runs locally with full access, you have two choices:

1. watch everything it does (which defeats the purpose of delegation), or

2. trust it completely (which is reckless).

Sandboxing gives you a third option … let it work freely inside a controlled space.

Two Surfaces, Two Sandbox Models

Codex runs on two very different surfaces, and each has its own sandboxing approach.

Cloud Threads (Codex App)

When you fire a task in the Codex app, it does not run on your machine.

Codex clones your repository into an isolated cloud environment, a microVM with its own file system, its own process space, and deliberately limited network access.

The network restriction is deliberate.

The agent cannot pip install new packages.

It cannot call external APIs. It cannot exfiltrate your code. This is a hard security boundary, not a soft guideline.

The output is always a PR or diff, never a direct edit to your working tree.

You review and merge. The agent never touches your actual files.

Local threads (CLI and IDE)

When you run Codex locally, through the CLI or the IDE extension, the agent operates on your machine.

No cloud.

No microVM. Your files, your terminal, your process space.

This is where sandboxing gets more nuanced, because the agent needs enough access to be useful but not so much that it becomes dangerous.

The sandbox is enforced at the OS level … platform-native enforcement on macOS, Linux, WSL and Windows.

This is not a prompt telling the model “please don’t touch these files.” It is the operating system preventing it.

Three Permission Modes

Codex gives you three levels of sandbox strictness:

read-only

The agent can look but not touch.

It reads files, analyses code, answers questions.

It cannot edit anything or run any command without explicit approval.

Use this when you want the agent to explore a codebase or review code without changing anything.

workspace-write

The default.

The agent can read files, edit files within the workspace, and run routine local commands … git, package managers, test runners.

It stays within the project directory. It cannot reach outside. This is where most day-to-day work happens.

danger-full-access

The sandbox is removed.

The agent has unrestricted access to your file system and network.

Use this only in disposable environments … CI containers, throwaway VMs, environments where damage does not matter.

Approval Policies

Layered on top of the sandbox modes are approval policies, they determine when the agent needs to ask you before acting:

The on-request policy is the sweet spot for most work.

The agent operates autonomously inside the sandbox …editing files, running tests, committing code and only pauses to ask when it wants to do something outside the boundary.

This reduces approval fatigue dramatically.

Instead of clicking “allow” forty times during a refactoring task, you get asked once when it wants to install a new dependency.

Configuration

The sandbox is configured in config.toml:

# ~/.codex/config.toml

sandbox_mode = “workspace-write”
approval_policy = “on-request”

[sandbox_workspace_write]
writable_roots = [
    “/Users/cobus/projects/my-app/src”,
    “/Users/cobus/projects/my-app/tests”,
]

# Command-prefix exceptions — allow specific commands
# without dropping the entire sandbox
[[rules]]
prefix = “npm test”
allow = true

[[rules]]
prefix = “python -m pytest”
allow = true

[[rules]]
prefix = “docker”
allow = false

The writable_roots setting is powerful.

It lets you scope the agent’s write access to specific directories.

The agent can edit anything under src/ and tests/, but node_modules/, .env, Dockerfile, and everything outside the project is read-only or blocked.

Command-prefix rules give you granular control without removing the sandbox entirely. You can allow npm testand pytestwhile blocking docker and curl — matching exactly the commands the agent needs for your workflow.

Cloud vs Local… the tradeoffs

The cloud sandbox is safer but slower.

The local sandbox is faster but requires more trust configuration.

The agent works on your actual files in real-time, and you can interact with it as it works.

But you need to configure the boundary correctly. the sandbox mode, the writable roots, the command rules.

Practical example

Refactoring with cloud sandbox

You have a monolithic utils.py with 2,000 lines.

You want it split into focused modules.

You:   “Split utils.py into separate modules by domain — auth,
        database, validation, formatting. Update all imports.
        Run the test suite.”

Codex: [clones repo into cloud sandbox]
       [reads utils.py, identifies function clusters]
       [creates auth.py, database.py, validation.py, formatting.py]
       [moves functions, updates __init__.py]
       [rewrites imports across 47 files]
       [runs pytest — 3 failures]
       [fixes circular import in database.py]
       [runs pytest — all pass]
       [creates PR with diff]

You:   [review PR 20 minutes later]
       [merge]

The entire process happened in an isolated clone. Your working tree was untouched.

Practical Example: Debugging with Local Sandbox

A test is failing. You want to debug interactively.

You:   “test_auth_flow is failing with a 401. Debug it.”

Codex: [reads test_auth_flow.py]
       [reads auth.py]
       [runs: pytest tests/test_auth_flow.py -v]
       [sees: token expiry check uses UTC, test fixture uses local time]
       [edits tests/conftest.py — fixes timezone in fixture]
       [runs: pytest tests/test_auth_flow.py -v]
       [passes]

You:   [see the fix in real-time, approve the edit]

This happened on your machine, in your working tree, in real-time.

The sandbox allowed pytest and file edits within the workspace but would have blocked any attempt to modify .env or reach outside the project.

The importance of this…

The sandbox pattern solves the fundamental tension in agentic AI … autonomy versus safety.

Without sandboxing, you get two bad options.

Either the agent asks permission for everything, which makes it slow and annoying … or you give it full access and hope for the best.

With sandboxing, the agent works freely within the boundary.

It is autonomous inside the box. The box is the guarantee.

This is the same pattern that made containers work for deployment.

Docker did not make applications trustworthy. It made the blast radius containable. Sandboxing does the same for AI agents.

Chief AI Evangelist @ Kore.ai | I’m passionate about exploring the intersection of AI and language. From Language Models, AI Agents to Agentic Applications, Development Frameworks & Data-Centric Productivity Tools, I share insights and ideas on how these technologies are shaping the future.

Sandboxing - Codex | OpenAI Developers
How Codex uses sandboxes across the Codex app, IDE, and CLIdevelopers.openai.com