concepts/sandboxing.md +38 −1
67 67
68Codex surfaces a startup warning when `bwrap` is missing or when the helper68Codex surfaces a startup warning when `bwrap` is missing or when the helper
69can't create the needed user namespace. On distributions that restrict this69can't create the needed user namespace. On distributions that restrict this
7070AppArmor setting, you can enable it with:AppArmor 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:
71 99
72```bash100```bash
73sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0101sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
131Managed network profiles use map tables such as159Managed network profiles use map tables such as
132`[permissions.<name>.network.domains]` and160`[permissions.<name>.network.domains]` and
133`[permissions.<name>.network.unix_sockets]` for domain and socket rules.161`[permissions.<name>.network.unix_sockets]` for domain and socket rules.
162Filesystem profiles can also deny reads for exact paths or glob patterns by
163setting matching entries to `"none"`; use this to keep files such as local
164secrets unreadable without turning off workspace writes.
134 165
135When a workflow needs a specific exception, use [rules](https://developers.openai.com/codex/rules). Rules166When 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 is167let 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 the170[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).171IDE-specific settings entry points, see [Codex IDE extension settings](https://developers.openai.com/codex/ide/settings).
141 172
173Automatic review, when available, doesn't change the sandbox boundary. It
174reviews approval requests, such as sandbox escalations or network access, while
175actions already allowed inside the sandbox run without extra review. See
176[Automatic approval reviews](https://developers.openai.com/codex/agent-approvals-security#automatic-approval-reviews)
177for the policy behavior.
178
142Platform details live in the platform-specific docs. For native Windows setup,179Platform details live in the platform-specific docs. For native Windows setup,
143behavior, and troubleshooting, see [Windows](https://developers.openai.com/codex/windows). For admin180behavior, and troubleshooting, see [Windows](https://developers.openai.com/codex/windows). For admin
144requirements and organization-level constraints on sandboxing and approvals, see181requirements and organization-level constraints on sandboxing and approvals, see