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

1# Sandboxing – Codex1# Sandbox

2 2 

3Sandboxing is the boundary that lets Codex act autonomously without giving it3The sandbox is the boundary that lets Codex act autonomously without giving it

4unrestricted access to your machine. When Codex runs local commands in the4unrestricted access to your machine. When Codex runs local commands in the

5**Codex app**, **IDE extension**, or **CLI**, those commands run inside a5**Codex app**, **IDE extension**, or **CLI**, those commands run inside a

6constrained environment instead of running with full access by default.6constrained environment instead of running with full access by default.

21those commands inherit the same sandbox boundaries.21those commands inherit the same sandbox boundaries.

22 22 

23Codex uses platform-native enforcement on each OS. The implementation differs23Codex uses platform-native enforcement on each OS. The implementation differs

24between macOS, Linux, WSL, and native Windows, but the idea is the same across24between 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 run25surfaces: give the agent a bounded place to work so routine tasks can run

26autonomously inside clear limits.26autonomously inside clear limits.

27 27 

28## Why it matters28## Why it matters

29 29 

30Sandboxing reduces approval fatigue. Instead of asking you to confirm every30The sandbox reduces approval fatigue. Instead of asking you to confirm every

31low-risk command, Codex can read files, make edits, and run routine project31low-risk command, Codex can read files, make edits, and run routine project

32commands within the boundary you already approved.32commands within the boundary you already approved.

33 33 

34It also gives you a clearer trust model for agentic work. You are not just34It 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 operating35trusting the agent's intentions; you are trusting that the agent is operating

36inside enforced limits. That makes it easier to let Codex work independently36inside enforced limits. That makes it easier to let Codex work independently

37while still knowing when it will stop and ask for help.37while still knowing when it will stop and ask for help.

38 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 

39## How you control it121## How you control it

40 122 

41Most people start with the permissions controls in the product.123Most people start with the permissions controls in the product.

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

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

46 128 

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

48 130 

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

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

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

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

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

58`sandbox_mode`, `approval_policy`, and140`sandbox_mode`, `approval_policy`, `approvals_reviewer`, and

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

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

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

62 144 

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

64 146 

65- `read-only`: Codex can inspect files, but it cannot edit files or run147- `read-only`: Codex can inspect files, but it can't edit files or run

66 commands without approval.148 commands without approval.

67- `workspace-write`: Codex can read files, edit within the workspace, and run149- `workspace-write`: Codex can read files, edit within the workspace, and run

68 routine local commands inside that boundary. This is the default low-friction150 routine local commands inside that boundary. This is the default low-friction

73 155 

74The common approval policies are:156The common approval policies are:

75 157 

76- `untrusted`: Codex asks before running commands that are not in its trusted158- `untrusted`: Codex asks before running commands that aren't in its trusted

77 set.159 set.

78- `on-request`: Codex works inside the sandbox by default and asks when it160- `on-request`: Codex works inside the sandbox by default and asks when it

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

80- `never`: Codex does not stop for approval prompts.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)).

81 170 

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

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

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

85`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.

86 178 

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

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

89you need a broader or narrower trust boundary, adjust the default sandbox mode181you need a broader or narrower trust boundary, adjust the default sandbox mode

90and approval policy instead of relying on ad hoc exceptions.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.

91 192 

92When 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

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

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

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

98 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 

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

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

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