concepts/sandboxing.md Codex Docs, 2026-05-01 18:29 UTC → 2026-05-18 22:01 UTC

52 52 

53On **Linux and WSL2**, install `bubblewrap` with your package manager first:53On **Linux and WSL2**, install `bubblewrap` with your package manager first:

54 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 

55```bash65```bash

56sudo apt install bubblewrap66sudo apt install bubblewrap

57```67```

58 68 

69 </div>

70 

71 <div slot="fedora">

72 

59```bash73```bash

60sudo dnf install bubblewrap74sudo dnf install bubblewrap

61```75```

62 76 

77 </div>

78</Tabs>

79 

63Codex uses the first `bwrap` executable it finds on `PATH`. If no `bwrap`80Codex uses the first `bwrap` executable it finds on `PATH`. If no `bwrap`

64executable is available, Codex falls back to a bundled helper, but that helper81executable is available, Codex falls back to a bundled helper, but that helper

65requires support for unprivileged user namespace creation. Installing the82requires support for unprivileged user namespace creation. Installing the

109the composer or chat input. That selector lets you rely on Codex's default126the composer or chat input. That selector lets you rely on Codex's default

110permissions, switch to full access, or use your custom configuration.127permissions, switch to full access, or use your custom configuration.

111 128 

112![Codex app permissions selector showing Default permissions, Full access, and Custom (config.toml)](/images/codex/app/permissions-selector-light.webp)129<PermissionModeSelectorDemo client:load />

113 130 

114In the CLI, use [`/permissions`](https://developers.openai.com/codex/cli/slash-commands#update-permissions-with-permissions)131In the CLI, use [`/permissions`](https://developers.openai.com/codex/cli/slash-commands#update-permissions-with-permissions)

115to switch modes during a session.132to switch modes during a session.

120configuration. Codex stores those defaults in `config.toml`, its local settings137configuration. Codex stores those defaults in `config.toml`, its local settings

121file. [Config basics](https://developers.openai.com/codex/config-basic) explains how it works, and the138file. [Config basics](https://developers.openai.com/codex/config-basic) explains how it works, and the

122[Configuration reference](https://developers.openai.com/codex/config-reference) documents the exact keys for139[Configuration reference](https://developers.openai.com/codex/config-reference) documents the exact keys for

123`sandbox_mode`, `approval_policy`, and140`sandbox_mode`, `approval_policy`, `approvals_reviewer`, and

124`sandbox_workspace_write.writable_roots`. Use those settings to decide how much141`sandbox_workspace_write.writable_roots`. Use those settings to decide how much

125autonomy Codex gets by default, which directories it can write to, and when it142autonomy Codex gets by default, which directories it can write to, when it

126should pause for approval.143should pause for approval, and who reviews eligible approval requests.

127 144 

128At a high level, the common sandbox modes are:145At a high level, the common sandbox modes are:

129 146 

144 needs to go beyond that boundary.161 needs to go beyond that boundary.

145- `never`: Codex doesn't stop for approval prompts.162- `never`: Codex doesn't stop for approval prompts.

146 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 

147Full access means using `sandbox_mode = "danger-full-access"` together with171Full access means using `sandbox_mode = "danger-full-access"` together with

148`approval_policy = "never"`. By contrast, the lower-risk local automation172`approval_policy = "never"`. By contrast, the lower-risk local automation

149preset is `sandbox_mode = "workspace-write"` together with173preset is `sandbox_mode = "workspace-write"` together with

150`approval_policy = "on-request"`, or the matching CLI flags174`approval_policy = "on-request"`, or the matching CLI flags

151`--sandbox workspace-write --ask-for-approval on-request`.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.

152 178 

153If you need Codex to work across more than one directory, writable roots let179If you need Codex to work across more than one directory, writable roots let

154you extend the places it can modify without removing the sandbox entirely. If180you extend the places it can modify without removing the sandbox entirely. If

171[Codex app features](https://developers.openai.com/codex/app/features#approvals-and-sandboxing), and for the197[Codex app features](https://developers.openai.com/codex/app/features#approvals-and-sandboxing), and for the

172IDE-specific settings entry points, see [Codex IDE extension settings](https://developers.openai.com/codex/ide/settings).198IDE-specific settings entry points, see [Codex IDE extension settings](https://developers.openai.com/codex/ide/settings).

173 199 

174Automatic review, when available, doesn't change the sandbox boundary. It200Automatic review, when available, does not change the sandbox boundary. It is

175reviews approval requests, such as sandbox escalations or network access, while201one possible `approvals_reviewer` for approval requests at that boundary, such

176actions already allowed inside the sandbox run without extra review. See202as sandbox escalations, blocked network access, or side-effecting tool calls

177[Automatic approval reviews](https://developers.openai.com/codex/agent-approvals-security#automatic-approval-reviews)203that still need approval. Actions already allowed inside the sandbox run

178for the policy behavior.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).

179 207 

180Platform details live in the platform-specific docs. For native Windows setup,208Platform details live in the platform-specific docs. For native Windows setup,

181behavior, and troubleshooting, see [Windows](https://developers.openai.com/codex/windows). For admin209behavior, and troubleshooting, see [Windows](https://developers.openai.com/codex/windows). For admin