concepts/sandboxing.md Codex Docs, 2026-04-18 18:18 UTC → 2026-05-14 07:00 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

67 84 

68Codex surfaces a startup warning when `bwrap` is missing or when the helper85Codex surfaces a startup warning when `bwrap` is missing or when the helper

69can't create the needed user namespace. On distributions that restrict this86can't create the needed user namespace. On distributions that restrict this

70AppArmor setting, you can enable it with: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:

71 116 

72```bash117```bash

73sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0118sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0

81the 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

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

83 128 

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

85 130 

86In 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)

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

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

93file. [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

94[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

95`sandbox_mode`, `approval_policy`, and140`sandbox_mode`, `approval_policy`, `approvals_reviewer`, and

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

97autonomy 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

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

99 144 

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

101 146 

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

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

118 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 

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

120`approval_policy = "never"`. By contrast, `--full-auto` is the lower-risk local172`approval_policy = "never"`. By contrast, the lower-risk local automation

121automation preset: `sandbox_mode = "workspace-write"` and173preset is `sandbox_mode = "workspace-write"` together with

122`approval_policy = "on-request"`.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.

123 178 

124If 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

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

131Managed network profiles use map tables such as186Managed network profiles use map tables such as

132`[permissions.<name>.network.domains]` and187`[permissions.<name>.network.domains]` and

133`[permissions.<name>.network.unix_sockets]` for domain and socket rules.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.

134 192 

135When a workflow needs a specific exception, use [rules](https://developers.openai.com/codex/rules). Rules193When a workflow needs a specific exception, use [rules](https://developers.openai.com/codex/rules). Rules

136let you allow, prompt, or forbid command prefixes outside the sandbox, which is194let you allow, prompt, or forbid command prefixes outside the sandbox, which is

139[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

140IDE-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).

141 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 

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

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

144requirements and organization-level constraints on sandboxing and approvals, see210requirements and organization-level constraints on sandboxing and approvals, see