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

117- `never`: Codex doesn't 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

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

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

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

134 188 

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

136let you allow, prompt, or forbid command prefixes outside the sandbox, which is190let 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 the193[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).194IDE-specific settings entry points, see [Codex IDE extension settings](https://developers.openai.com/codex/ide/settings).

141 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 

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

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

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