concepts/sandboxing.md Codex Docs, 2026-02-24 00:33 UTC → 2026-05-01 18:29 UTC

1# Sandbox

2 

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

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

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

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

7 

8That environment defines what Codex can do on its own, such as which files it

9can modify and whether commands can use the network. When a task stays inside

10those boundaries, Codex can keep moving without stopping for confirmation. When

11it needs to go beyond them, Codex falls back to the approval flow.

12 

13Sandboxing and approvals are different controls that work together. The

14 sandbox defines technical boundaries. The approval policy decides when Codex

15 must stop and ask before crossing them.

16 

17## What the sandbox does

18 

19The sandbox applies to spawned commands, not just to Codex's built-in file

20operations. If Codex runs tools like `git`, package managers, or test runners,

21those commands inherit the same sandbox boundaries.

22 

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

24between 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 run

26autonomously inside clear limits.

27 

28## Why it matters

29 

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

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

32commands within the boundary you already approved.

33 

34It 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 operating

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

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

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```bash

56sudo apt install bubblewrap

57```

58 

59```bash

60sudo dnf install bubblewrap

61```

62 

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

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

65requires support for unprivileged user namespace creation. Installing the

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

67 

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

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

70AppArmor setting, prefer loading the `bwrap` AppArmor profile so `bwrap` can

71keep working without disabling the restriction globally.

72 

73**Ubuntu AppArmor note:** On Ubuntu 25.04, installing `bubblewrap` from

74 Ubuntu's package repository should work without extra AppArmor setup. The

75 `bwrap-userns-restrict` profile ships in the `apparmor` package at

76 `/etc/apparmor.d/bwrap-userns-restrict`.

77 

78On Ubuntu 24.04, Codex may still warn that it can't create the needed user

79namespace after `bubblewrap` is installed. Copy and load the extra profile:

80 

81```bash

82sudo apt update

83sudo apt install apparmor-profiles apparmor-utils

84sudo install -m 0644 \

85 /usr/share/apparmor/extra-profiles/bwrap-userns-restrict \

86 /etc/apparmor.d/bwrap-userns-restrict

87sudo apparmor_parser -r /etc/apparmor.d/bwrap-userns-restrict

88```

89 

90`apparmor_parser -r` loads the profile into the kernel without a reboot. You

91can also reload all AppArmor profiles:

92 

93```bash

94sudo systemctl reload apparmor.service

95```

96 

97If that profile is unavailable or does not resolve the issue, you can disable

98the AppArmor unprivileged user namespace restriction with:

99 

100```bash

101sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0

102```

103 

104## How you control it

105 

106Most people start with the permissions controls in the product.

107 

108In the Codex app and IDE, you choose a mode from the permissions selector under

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

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

111 

112![Codex app permissions selector showing Default permissions, Full access, and Custom (config.toml)](/images/codex/app/permissions-selector-light.webp)

113 

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

115to switch modes during a session.

116 

117## Configure defaults

118 

119If you want Codex to start with the same behavior every time, use a custom

120configuration. 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 the

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

123`sandbox_mode`, `approval_policy`, and

124`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 it

126should pause for approval.

127 

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

129 

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

131 commands without approval.

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

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

134 mode for local work.

135- `danger-full-access`: Codex runs without sandbox restrictions. This removes

136 the filesystem and network boundaries and should be used only when you want

137 Codex to act with full access.

138 

139The common approval policies are:

140 

141- `untrusted`: Codex asks before running commands that aren't in its trusted

142 set.

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

144 needs to go beyond that boundary.

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

146 

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

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

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

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

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

152 

153If 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. If

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

156and approval policy instead of relying on one-off exceptions.

157 

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

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

160Managed network profiles use map tables such as

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

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

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

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

165secrets unreadable without turning off workspace writes.

166 

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

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

169often a better fit than broadly expanding access. For a higher-level overview

170of approvals and sandbox behavior in the app, see

171[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).

173 

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

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

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

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

178for the policy behavior.

179 

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

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

182requirements and organization-level constraints on sandboxing and approvals, see

183[Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security).