87cce88f48
- Added the new codex-windows-sandbox crate that builds both a library
entry point (run_windows_sandbox_capture) and a CLI executable to launch
commands inside a Windows restricted-token sandbox, including ACL
management, capability SID provisioning, network lockdown, and output
capture
(windows-sandbox-rs/src/lib.rs:167, windows-sandbox-rs/src/main.rs:54).
- Introduced the experimental WindowsSandbox feature flag and wiring so
Windows builds can opt into the sandbox:
SandboxType::WindowsRestrictedToken, the in-process execution path, and
platform sandbox selection now honor the flag (core/src/features.rs:47,
core/src/config.rs:1224, core/src/safety.rs:19,
core/src/sandboxing/mod.rs:69, core/src/exec.rs:79,
core/src/exec.rs:172).
- Updated workspace metadata to include the new crate and its
Windows-specific dependencies so the core crate can link against it
(codex-rs/
Cargo.toml:91, core/Cargo.toml:86).
- Added a PowerShell bootstrap script that installs the Windows
toolchain, required CLI utilities, and builds the workspace to ease
development
on the platform (scripts/setup-windows.ps1:1).
- Landed a Python smoke-test suite that exercises
read-only/workspace-write policies, ACL behavior, and network denial for
the Windows sandbox
binary (windows-sandbox-rs/sandbox_smoketests.py:1).
96 lines
6.5 KiB
Markdown
96 lines
6.5 KiB
Markdown
## Sandbox & approvals
|
|
|
|
What Codex is allowed to do is governed by a combination of **sandbox modes** (what Codex is allowed to do without supervision) and **approval policies** (when you must confirm an action). This page explains the options, how they interact, and how the sandbox behaves on each platform.
|
|
|
|
### Approval policies
|
|
|
|
Codex starts conservatively. Until you explicitly tell it a workspace is trusted, the CLI defaults to **read-only sandboxing** with the `read-only` approval preset. Codex can inspect files and answer questions, but every edit or command requires approval.
|
|
|
|
When you mark a workspace as trusted (for example via the onboarding prompt or `/approvals` → “Trust this directory”), Codex upgrades the default preset to **Auto**: sandboxed writes inside the workspace with `AskForApproval::OnRequest`. Codex only interrupts you when it needs to leave the workspace or rerun something outside the sandbox.
|
|
|
|
If you want maximum guardrails for a trusted repo, switch back to Read Only from the `/approvals` picker. If you truly need hands-off automation, use `Full Access`—but be deliberate, because that skips both the sandbox and approvals.
|
|
|
|
#### Defaults and recommendations
|
|
|
|
- Every session starts in a sandbox. Until a repo is trusted, Codex enforces read-only access and will prompt before any write or command.
|
|
- Marking a repo as trusted switches the default preset to Auto (`workspace-write` + `ask-for-approval on-request`) so Codex can keep iterating locally without nagging you.
|
|
- The workspace always includes the current directory plus temporary directories like `/tmp`. Use `/status` to confirm the exact writable roots.
|
|
- You can override the defaults from the command line at any time:
|
|
- `codex --sandbox read-only --ask-for-approval on-request`
|
|
- `codex --sandbox workspace-write --ask-for-approval on-request`
|
|
|
|
### Can I run without ANY approvals?
|
|
|
|
Yes, you can disable all approval prompts with `--ask-for-approval never`. This option works with all `--sandbox` modes, so you still have full control over Codex's level of autonomy. It will make its best attempt with whatever constraints you provide.
|
|
|
|
### Common sandbox + approvals combinations
|
|
|
|
| Intent | Flags | Effect |
|
|
| ---------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| Safe read-only browsing | `--sandbox read-only --ask-for-approval on-request` | Codex can read files and answer questions. Codex requires approval to make edits, run commands, or access network. |
|
|
| Read-only non-interactive (CI) | `--sandbox read-only --ask-for-approval never` | Reads only; never escalates |
|
|
| Let it edit the repo, ask if risky | `--sandbox workspace-write --ask-for-approval on-request` | Codex can read files, make edits, and run commands in the workspace. Codex requires approval for actions outside the workspace or for network access. |
|
|
| Auto (preset; trusted repos) | `--full-auto` (equivalent to `--sandbox workspace-write` + `--ask-for-approval on-request`) | Codex runs sandboxed commands that can write inside the workspace without prompting. Escalates only when it must leave the sandbox. |
|
|
| YOLO (not recommended) | `--dangerously-bypass-approvals-and-sandbox` (alias: `--yolo`) | No sandbox; no prompts |
|
|
|
|
> Note: In `workspace-write`, network is disabled by default unless enabled in config (`[sandbox_workspace_write].network_access = true`).
|
|
|
|
#### Fine-tuning in `config.toml`
|
|
|
|
```toml
|
|
# approval mode
|
|
approval_policy = "untrusted"
|
|
sandbox_mode = "read-only"
|
|
|
|
# full-auto mode
|
|
approval_policy = "on-request"
|
|
sandbox_mode = "workspace-write"
|
|
|
|
# Optional: allow network in workspace-write mode
|
|
[sandbox_workspace_write]
|
|
network_access = true
|
|
```
|
|
|
|
You can also save presets as **profiles**:
|
|
|
|
```toml
|
|
[profiles.full_auto]
|
|
approval_policy = "on-request"
|
|
sandbox_mode = "workspace-write"
|
|
|
|
[profiles.readonly_quiet]
|
|
approval_policy = "never"
|
|
sandbox_mode = "read-only"
|
|
```
|
|
|
|
### Sandbox mechanics by platform {#platform-sandboxing-details}
|
|
|
|
The mechanism Codex uses to enforce the sandbox policy depends on your OS:
|
|
|
|
- **macOS 12+** uses **Apple Seatbelt**. Codex invokes `sandbox-exec` with a profile that corresponds to the selected `--sandbox` mode, constraining filesystem and network access at the OS level.
|
|
- **Linux** combines **Landlock** and **seccomp** APIs to approximate the same guarantees. Kernel support is required; older kernels may not expose the necessary features.
|
|
- **Windows (experimental)**:
|
|
- Launches commands inside a restricted token derived from an AppContainer profile.
|
|
- Grants only specifically requested filesystem capabilities by attaching capability SIDs to that profile.
|
|
- Disables outbound network access by overriding proxy-related environment variables and inserting stub executables for common network tools.
|
|
|
|
Windows sandbox support remains highly experimental. It cannot prevent file writes, deletions, or creations in any directory where the Everyone SID already has write permissions (for example, world-writable folders).
|
|
|
|
In containerized Linux environments (for example Docker), sandboxing may not work when the host or container configuration does not expose Landlock/seccomp. In those cases, configure the container to provide the isolation you need and run Codex with `--sandbox danger-full-access` (or the shorthand `--dangerously-bypass-approvals-and-sandbox`) inside that container.
|
|
|
|
### Experimenting with the Codex Sandbox
|
|
|
|
To test how commands behave under Codex's sandbox, use the CLI helpers:
|
|
|
|
```
|
|
# macOS
|
|
codex sandbox macos [--full-auto] [COMMAND]...
|
|
|
|
# Linux
|
|
codex sandbox linux [--full-auto] [COMMAND]...
|
|
|
|
# Legacy aliases
|
|
codex debug seatbelt [--full-auto] [COMMAND]...
|
|
codex debug landlock [--full-auto] [COMMAND]...
|
|
```
|