concepts/sandboxing.md +211 −0 added
1# Sandbox
2
3The sandbox is the boundary that lets Codex act autonomously without giving it
4unrestricted access to your machine. When Codex runs local commands in the
5**Codex app**, **IDE extension**, or **CLI**, those commands run inside a
6constrained environment instead of running with full access by default.
7
8That environment defines what Codex can do on its own, such as which files it
9can modify and whether commands can use the network. When a task stays inside
10those boundaries, Codex can keep moving without stopping for confirmation. When
11it needs to go beyond them, Codex falls back to the approval flow.
12
13Sandboxing and approvals are different controls that work together. The
14 sandbox defines technical boundaries. The approval policy decides when Codex
15 must stop and ask before crossing them.
16
17## What the sandbox does
18
19The sandbox applies to spawned commands, not just to Codex's built-in file
20operations. If Codex runs tools like `git`, package managers, or test runners,
21those commands inherit the same sandbox boundaries.
22
23Codex uses platform-native enforcement on each OS. The implementation differs
24between macOS, Linux, WSL2, and native Windows, but the idea is the same across
25surfaces: give the agent a bounded place to work so routine tasks can run
26autonomously inside clear limits.
27
28## Why it matters
29
30The sandbox reduces approval fatigue. Instead of asking you to confirm every
31low-risk command, Codex can read files, make edits, and run routine project
32commands within the boundary you already approved.
33
34It also gives you a clearer trust model for agentic work. You aren't just
35trusting the agent's intentions; you are trusting that the agent is operating
36inside enforced limits. That makes it easier to let Codex work independently
37while still knowing when it will stop and ask for help.
38
39## Getting started
40
41Codex applies sandboxing automatically when you use the default permissions
42mode.
43
44### Prerequisites
45
46On **macOS**, sandboxing works out of the box using the built-in Seatbelt
47framework.
48
49On **Windows**, Codex uses the native [Windows
50sandbox](https://developers.openai.com/codex/windows#windows-sandbox) when you run in PowerShell and the
51Linux sandbox implementation when you run in WSL2.
52
53On **Linux and WSL2**, install `bubblewrap` with your package manager first:
54
55<Tabs
56 id="codex-sandboxing-prerequisites"
57 param="sandbox-os"
58 tabs={[
59 { id: "ubuntu-debian", label: "Ubuntu/Debian" },
60 { id: "fedora", label: "Fedora" },
61 ]}
62>
63 <div slot="ubuntu-debian">
64
65```bash
66sudo apt install bubblewrap
67```
68
69 </div>
70
71 <div slot="fedora">
72
73```bash
74sudo dnf install bubblewrap
75```
76
77 </div>
78</Tabs>
79
80Codex uses the first `bwrap` executable it finds on `PATH`. If no `bwrap`
81executable is available, Codex falls back to a bundled helper, but that helper
82requires support for unprivileged user namespace creation. Installing the
83distribution package that provides `bwrap` keeps this setup reliable.
84
85Codex surfaces a startup warning when `bwrap` is missing or when the helper
86can't create the needed user namespace. On distributions that restrict this
87AppArmor setting, prefer loading the `bwrap` AppArmor profile so `bwrap` can
88keep working without disabling the restriction globally.
89
90**Ubuntu AppArmor note:** On Ubuntu 25.04, installing `bubblewrap` from
91 Ubuntu's package repository should work without extra AppArmor setup. The
92 `bwrap-userns-restrict` profile ships in the `apparmor` package at
93 `/etc/apparmor.d/bwrap-userns-restrict`.
94
95On Ubuntu 24.04, Codex may still warn that it can't create the needed user
96namespace after `bubblewrap` is installed. Copy and load the extra profile:
97
98```bash
99sudo apt update
100sudo apt install apparmor-profiles apparmor-utils
101sudo install -m 0644 \
102 /usr/share/apparmor/extra-profiles/bwrap-userns-restrict \
103 /etc/apparmor.d/bwrap-userns-restrict
104sudo apparmor_parser -r /etc/apparmor.d/bwrap-userns-restrict
105```
106
107`apparmor_parser -r` loads the profile into the kernel without a reboot. You
108can also reload all AppArmor profiles:
109
110```bash
111sudo systemctl reload apparmor.service
112```
113
114If that profile is unavailable or does not resolve the issue, you can disable
115the AppArmor unprivileged user namespace restriction with:
116
117```bash
118sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
119```
120
121## How you control it
122
123Most people start with the permissions controls in the product.
124
125In the Codex app and IDE, you choose a mode from the permissions selector under
126the composer or chat input. That selector lets you rely on Codex's default
127permissions, switch to full access, or use your custom configuration.
128
129<PermissionModeSelectorDemo client:load />
130
131In the CLI, use [`/permissions`](https://developers.openai.com/codex/cli/slash-commands#update-permissions-with-permissions)
132to switch modes during a session.
133
134## Configure defaults
135
136If you want Codex to start with the same behavior every time, use a custom
137configuration. Codex stores those defaults in `config.toml`, its local settings
138file. [Config basics](https://developers.openai.com/codex/config-basic) explains how it works, and the
139[Configuration reference](https://developers.openai.com/codex/config-reference) documents the exact keys for
140`sandbox_mode`, `approval_policy`, `approvals_reviewer`, and
141`sandbox_workspace_write.writable_roots`. Use those settings to decide how much
142autonomy Codex gets by default, which directories it can write to, when it
143should pause for approval, and who reviews eligible approval requests.
144
145At a high level, the common sandbox modes are:
146
147- `read-only`: Codex can inspect files, but it can't edit files or run
148 commands without approval.
149- `workspace-write`: Codex can read files, edit within the workspace, and run
150 routine local commands inside that boundary. This is the default low-friction
151 mode for local work.
152- `danger-full-access`: Codex runs without sandbox restrictions. This removes
153 the filesystem and network boundaries and should be used only when you want
154 Codex to act with full access.
155
156The common approval policies are:
157
158- `untrusted`: Codex asks before running commands that aren't in its trusted
159 set.
160- `on-request`: Codex works inside the sandbox by default and asks when it
161 needs to go beyond that boundary.
162- `never`: Codex doesn't stop for approval prompts.
163
164When approvals are interactive, you can also choose who reviews them with
165`approvals_reviewer`:
166
167- `user`: approval prompts surface to the user. This is the default.
168- `auto_review`: eligible approval prompts go to a reviewer agent (see
169 [Auto-review](https://developers.openai.com/codex/concepts/sandboxing/auto-review)).
170
171Full access means using `sandbox_mode = "danger-full-access"` together with
172`approval_policy = "never"`. By contrast, the lower-risk local automation
173preset is `sandbox_mode = "workspace-write"` together with
174`approval_policy = "on-request"`, or the matching CLI flags
175`--sandbox workspace-write --ask-for-approval on-request`. You can then keep
176`approvals_reviewer = "user"` for manual approvals or set
177`approvals_reviewer = "auto_review"` for automatic approval review.
178
179If you need Codex to work across more than one directory, writable roots let
180you extend the places it can modify without removing the sandbox entirely. If
181you need a broader or narrower trust boundary, adjust the default sandbox mode
182and approval policy instead of relying on one-off exceptions.
183
184For reusable permission sets, set `default_permissions` to a named profile and
185define `[permissions.<name>.filesystem]` or `[permissions.<name>.network]`.
186Managed network profiles use map tables such as
187`[permissions.<name>.network.domains]` and
188`[permissions.<name>.network.unix_sockets]` for domain and socket rules.
189Filesystem profiles can also deny reads for exact paths or glob patterns by
190setting matching entries to `"none"`; use this to keep files such as local
191secrets unreadable without turning off workspace writes.
192
193When a workflow needs a specific exception, use [rules](https://developers.openai.com/codex/rules). Rules
194let you allow, prompt, or forbid command prefixes outside the sandbox, which is
195often a better fit than broadly expanding access. For a higher-level overview
196of approvals and sandbox behavior in the app, see
197[Codex app features](https://developers.openai.com/codex/app/features#approvals-and-sandboxing), and for the
198IDE-specific settings entry points, see [Codex IDE extension settings](https://developers.openai.com/codex/ide/settings).
199
200Automatic review, when available, does not change the sandbox boundary. It is
201one possible `approvals_reviewer` for approval requests at that boundary, such
202as sandbox escalations, blocked network access, or side-effecting tool calls
203that still need approval. Actions already allowed inside the sandbox run
204without extra review. For the reviewer lifecycle, trigger types, denial
205semantics, and configuration details, see
206[Auto-review](https://developers.openai.com/codex/concepts/sandboxing/auto-review).
207
208Platform details live in the platform-specific docs. For native Windows setup,
209behavior, and troubleshooting, see [Windows](https://developers.openai.com/codex/windows). For admin
210requirements and organization-level constraints on sandboxing and approvals, see
211[Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security).