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

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 

63Codex uses the system `bwrap` at `/usr/bin/bwrap` when it is available. If it77 </div>

64is missing, Codex falls back to a bundled helper, but that helper requires78</Tabs>

65unprivileged user namespaces. Installing your distro’s `bubblewrap` package is79 

66the most reliable setup.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```

67 113 

68Codex surfaces a startup warning when `bwrap` is missing or cannot create user114If that profile is unavailable or does not resolve the issue, you can disable

69namespaces. On distributions that restrict them with AppArmor, you can enable115the AppArmor unprivileged user namespace restriction with:

70them 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<div class="not-prose max-w-[22rem] mr-auto mb-6">

130 <img src="https://developers.openai.com/images/codex/app/permissions-selector-light.webp"

131 alt="Codex app permissions selector showing Default permissions, Full access, and Custom (config.toml)"

132 class="block h-auto w-full mx-0!"

133 />

134</div>

85 135 

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

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

99 149 

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

101 151 

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

103 commands without approval.153 commands without approval.

104- `workspace-write`: Codex can read files, edit within the workspace, and run154- `workspace-write`: Codex can read files, edit within the workspace, and run

105 routine local commands inside that boundary. This is the default low-friction155 routine local commands inside that boundary. This is the default low-friction

110 160 

111The common approval policies are:161The common approval policies are:

112 162 

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

114 set.164 set.

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

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

117- `never`: Codex does not stop for approval prompts.167- `never`: Codex doesn't stop for approval prompts.

118 168 

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

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

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

122`approval_policy = "on-request"`.172`approval_policy = "on-request"`, or the matching CLI flags

173`--sandbox workspace-write --ask-for-approval on-request`.

123 174 

124If you need Codex to work across more than one directory, writable roots let175If 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. If176you extend the places it can modify without removing the sandbox entirely. If

126you need a broader or narrower trust boundary, adjust the default sandbox mode177you need a broader or narrower trust boundary, adjust the default sandbox mode

127and approval policy instead of relying on ad hoc exceptions.178and approval policy instead of relying on one-off exceptions.

179 

180For reusable permission sets, set `default_permissions` to a named profile and

181define `[permissions.<name>.filesystem]` or `[permissions.<name>.network]`.

182Managed network profiles use map tables such as

183`[permissions.<name>.network.domains]` and

184`[permissions.<name>.network.unix_sockets]` for domain and socket rules.

185Filesystem profiles can also deny reads for exact paths or glob patterns by

186setting matching entries to `"none"`; use this to keep files such as local

187secrets unreadable without turning off workspace writes.

128 188 

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

130let you allow, prompt, or forbid command prefixes outside the sandbox, which is190let you allow, prompt, or forbid command prefixes outside the sandbox, which is

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

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

135 195 

196Automatic review, when available, doesn't change the sandbox boundary. It

197reviews approval requests, such as sandbox escalations or network access, while

198actions already allowed inside the sandbox run without extra review. See

199[Automatic approval reviews](https://developers.openai.com/codex/agent-approvals-security#automatic-approval-reviews)

200for the policy behavior.

201 

136Platform details live in the platform-specific docs. For native Windows setup,202Platform details live in the platform-specific docs. For native Windows setup,

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

138requirements and organization-level constraints on sandboxing and approvals, see204requirements and organization-level constraints on sandboxing and approvals, see