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

60sudo dnf install bubblewrap60sudo dnf install bubblewrap

61```61```

62 62 

63Codex uses the system `bwrap` at `/usr/bin/bwrap` when it is available. If it63Codex uses the first `bwrap` executable it finds on `PATH`. If no `bwrap`

64is missing, Codex falls back to a bundled helper, but that helper requires64executable is available, Codex falls back to a bundled helper, but that helper

65unprivileged user namespaces. Installing your distro’s `bubblewrap` package is65requires support for unprivileged user namespace creation. Installing the

66the most reliable setup.66distribution package that provides `bwrap` keeps this setup reliable.

67 67 

68Codex surfaces a startup warning when `bwrap` is missing or cannot create user68Codex surfaces a startup warning when `bwrap` is missing or when the helper

69namespaces. On distributions that restrict them with AppArmor, you can enable69can't create the needed user namespace. On distributions that restrict this

70them with:70AppArmor setting, you can enable it with:

71 71 

72```bash72```bash

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

99 99 

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

101 101 

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

103 commands without approval.103 commands without approval.

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

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

110 110 

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

112 112 

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

114 set.114 set.

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

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

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

118 118 

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

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

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

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

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

128 

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

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

131Managed network profiles use map tables such as

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

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

128 134 

129When a workflow needs a specific exception, use [rules](https://developers.openai.com/codex/rules). Rules135When 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 is136let you allow, prompt, or forbid command prefixes outside the sandbox, which is