mirror of
https://github.com/openai/codex.git
synced 2026-11-18 22:20:48 +00:00
## Why Managed proxy routes require bubblewrap's network namespace even when `features.use_legacy_landlock` is enabled. WSL1 compatibility checks and helper arguments need to agree on the effective mode. ## What changed Resolve bubblewrap or legacy Landlock once and use that mode for both the WSL1 check and the `codex-linux-sandbox` arguments. Use Linux sandbox naming for the shared launcher and CLI code, and preserve the published analytics category for a missing helper executable. ## Testing Unit tests exercise the production argument builder, including managed network context serialization when legacy Landlock is requested. They also cover which sandbox configurations WSL1 accepts and rejects. GitOrigin-RevId: 619ab9d3eef965de6bc6cb13ff8a33132018abcf
125 lines
5.9 KiB
Markdown
125 lines
5.9 KiB
Markdown
# codex-core
|
|
|
|
This crate implements the business logic for Codex. It is designed to be used by the various Codex UIs written in Rust.
|
|
|
|
## Wine-exec integration tests
|
|
|
|
On x86-64 Linux, run the shared suite against the Windows exec server with
|
|
`bazel test //codex-rs/core:core-all-wine-exec-test`.
|
|
|
|
Local execution targets the host OS, Docker targets Linux, and Wine exec targets
|
|
Windows. Choose the skip macro by what the test depends on:
|
|
|
|
- `skip_if_target_windows!`: Windows target behavior.
|
|
- `skip_if_host_windows!`: Windows host constraints.
|
|
- `skip_if_remote!`: Local-only test behavior.
|
|
- `skip_if_no_remote_env!`: Remote-only test behavior.
|
|
- `skip_if_wine_exec!`: Wine-specific runner debt.
|
|
|
|
## Dependencies
|
|
|
|
Note that `codex-core` makes some assumptions about certain helper utilities being available in the environment. Currently, this support matrix is:
|
|
|
|
### macOS
|
|
|
|
Expects `/usr/bin/sandbox-exec` to be present.
|
|
|
|
When using the workspace-write sandbox policy, the Seatbelt profile allows
|
|
writes under the configured writable roots while keeping `.git` (directory or
|
|
pointer file), the resolved `gitdir:` target, and `.codex` read-only.
|
|
|
|
Network access and filesystem read/write roots are controlled by
|
|
`SandboxPolicy`. Seatbelt consumes the resolved policy and enforces it.
|
|
|
|
Seatbelt also keeps the legacy default preferences read access
|
|
(`user-preference-read`) needed for cfprefs-backed macOS behavior.
|
|
|
|
### Linux
|
|
|
|
Expects the binary containing `codex-core` to run the equivalent of `codex sandbox` when `arg0` is `codex-linux-sandbox`. See the `codex-arg0` crate for details.
|
|
|
|
The Linux sandbox accepts both legacy `sandbox_mode` configs and permission
|
|
profiles. Bubblewrap enforces filesystem restrictions and provides the network
|
|
namespace for managed proxy routes. A managed route selects bubblewrap even
|
|
when `features.use_legacy_landlock` is set. Without a managed route, the helper
|
|
rejects legacy Landlock if the policy restricts filesystem writes. With full
|
|
disk write access it can apply network restrictions in process.
|
|
|
|
The Linux sandbox helper prefers the first `bwrap` found on `PATH` outside the
|
|
current working directory whenever it is available. If `bwrap` is present but
|
|
too old to support `--argv0`, the helper keeps using system bubblewrap and
|
|
switches to a no-`--argv0` compatibility path for the inner re-exec. If
|
|
`bwrap` is missing, it falls back to the bundled `codex-resources/bwrap`
|
|
binary shipped with Codex and Codex surfaces a startup warning through its
|
|
normal notification path instead of printing directly from the sandbox helper.
|
|
Codex also surfaces a startup warning when bubblewrap cannot create user
|
|
namespaces. WSL2 uses the normal Linux bubblewrap path. WSL1 is not supported
|
|
for bubblewrap sandboxing because it cannot create the required user
|
|
namespaces, so Codex rejects sandboxed shell commands that would enter the
|
|
bubblewrap path before invoking `bwrap`.
|
|
|
|
### Windows
|
|
|
|
Legacy `SandboxPolicy` / `sandbox_mode` configs are still supported on
|
|
Windows. Legacy `read-only` and `workspace-write` policies imply full
|
|
filesystem read access; exact readable roots are represented by split
|
|
filesystem policies instead.
|
|
|
|
The elevated Windows sandbox also supports:
|
|
|
|
- legacy `ReadOnly` and `WorkspaceWrite` behavior
|
|
- split filesystem policies that need exact readable roots, exact writable
|
|
roots, or extra read-only carveouts under writable roots
|
|
- backend-managed system read roots required for basic execution, such as
|
|
`C:\Windows`, `C:\Program Files`, `C:\Program Files (x86)`, and
|
|
`C:\ProgramData`, when a split filesystem policy requests platform defaults
|
|
|
|
The unelevated restricted-token backend still supports the legacy full-read
|
|
Windows model for legacy `ReadOnly` and `WorkspaceWrite` behavior. It also
|
|
supports a narrow split-filesystem subset: full-read split policies whose
|
|
writable roots still match the legacy `WorkspaceWrite` root set, but add extra
|
|
read-only carveouts under those writable roots.
|
|
|
|
New `[permissions]` / split filesystem policies remain supported on Windows
|
|
only when they can be enforced directly by the selected Windows backend or
|
|
round-trip through the legacy `SandboxPolicy` model without changing semantics.
|
|
Policies that would require direct explicit unreadable carveouts (`none`) or
|
|
reopened writable descendants under read-only carveouts still fail closed
|
|
instead of running with weaker enforcement.
|
|
|
|
### All Platforms
|
|
|
|
Expects the binary containing `codex-core` to simulate the virtual
|
|
`apply_patch` CLI when `arg1` is `--codex-run-as-apply-patch`. See the
|
|
`codex-arg0` crate for details.
|
|
|
|
## Runtime authentication (experimental)
|
|
|
|
Runtime authentication is off by default. To enable it in `config.toml`:
|
|
|
|
```toml
|
|
[features.runtime_agent_instances]
|
|
enabled = true
|
|
mode = "dual_header"
|
|
```
|
|
|
|
`dual_header` sends the existing actor credential and a fresh agent assertion.
|
|
`assertion_only` sends only the assertion. The latter requires backend support;
|
|
registration failures do not fall back to credential-only requests. Non-OpenAI
|
|
providers and third-party MCP authentication keep their existing behavior.
|
|
|
|
The same table in `requirements.toml` pins enablement and mode. A conflicting
|
|
explicit mode is rejected. The older boolean `runtime_agent_instances = true`
|
|
still works and uses the default mode (`dual_header`) unless requirements pin it.
|
|
Deliver typed requirements only to client versions that understand them.
|
|
|
|
The harness owns the runtime and its memory-only signing key. Ordinary token
|
|
refreshes reuse it; a different credential source or actor context requires a new
|
|
runtime. When runtime authentication is selected, legacy `AgentIdentity`
|
|
credentials migrate to saved OAuth credentials for the same actor and remove the
|
|
persisted signing key. If no matching actor credential exists, a supported
|
|
sign-in is required. Ordinary credential loading does not perform this migration.
|
|
|
|
Cloud-config bundle and requirements fetches retain their endpoint-restricted
|
|
bootstrap authentication, including refreshes after runtime initialization.
|