docker/sbx-kit-codex repository overview

⁠codex

A standalone workload kit (kind: workload, schemaVersion: "3") for Codex CLI⁠, OpenAI's agentic coding CLI. The kit runs codex as the entrypoint with Codex's own approval gate and filesystem sandbox turned off — the container is the sandbox — and authenticates through a single openai credential that works from either an API key or a ChatGPT login.

Codex was previously a built-in sbx agent, run as sbx run codex. This kit replaces that. A v3 workload's layers are the sandbox's root filesystem, so the kit is its own image: the content recipe is codex.dockerfile⁠ beside the descriptor, built on docker/sandbox-templates:shell-docker rather than tracking the docker/sandbox-templates release train.

Prefer Codex layered onto something else rather than as the whole sandbox? See codex-mixin⁠, which makes the same declarations as an overlay.

⁠Prerequisites

Any one of these works — the kit adapts to what it finds:

• OPENAI_API_KEY bound on your host. The proxy authenticates outbound requests to api.openai.com for you.
• A ChatGPT login stored as your host's openai credential. The kit points Codex at a ChatGPT-backed model provider and the proxy spends the OAuth token on your behalf.
• Nothing at all. Codex starts unauthenticated and prompts you to log in on first use, inside the sandbox.

⁠Usage

sbx run "docker.io/docker/sbx-kit-codex:latest"

Or from a git URL targeting this repo:

sbx run "git+https://github.com/docker/sbx-kits-contrib.git#dir=codex"

Or with a local clone of this repo:

sbx run ./codex/

The trailing codex is required, not redundant: sbx enforces that the agent name matches the workload kit being run. A v3 descriptor carries no name: — identity is the reference the kit is consumed by — and the matchable name the kit offers is its provides: ["codex"].

⁠Passing arguments

The entrypoint is codex --dangerously-bypass-approvals-and-sandbox, so anything you pass is appended after that flag. The flag is not optional housekeeping: an approval prompt in a headless sandbox has nobody to answer it, and the isolation Codex would otherwise provide for itself is already provided from the outside by the container.

The same intent is written into ~/.codex/config.toml as approval_policy = "never" and sandbox_mode = "danger-full-access", so the behaviour survives a session started by something other than the entrypoint — sbx exec, or one of the mixins below.

⁠Opening links

BROWSER is set to xdg-open, and the image installs xdg-utils so that program is really there. A kit that builds its own image has no excuse for pointing BROWSER at something it never shipped, and the package costs roughly 400 KB with no dependencies once its X11 recommends are skipped.

The sandbox still has no browser and no display, so a link does not literally open: xdg-open answers no method available for opening ..., exits non-zero, and Codex prints the URL for you to follow on your own machine. What changes is that the failure is a real answer from a real tool rather than a command-not-found from the kit's own configuration.

⁠How auth works

The kit declares one credential, openai, carrying both an apiKey and an oauth block. Which one is live is decided on the host, and the kit is told the outcome through SBX_CRED_OPENAI_MODE — one of apikey, oauth, or none (a host with both collapses to oauth). The install hook branches on it and writes ~/.codex/config.toml and ~/.codex/auth.json accordingly:

Three things about that table are deliberate:

• forced_login_method = "api" in both managed modes. The placeholder in auth.json is the entire auth story there, so a remote client must not be able to replace it with a sandbox-local ChatGPT login. none mode deliberately allows that login — it is the only way to authenticate at all.
• auth.json is removed, not blanked, in none mode. A leftover proxy-managed placeholder would be sent to OpenAI verbatim and come back a 401, which is a much more confusing failure than "please log in".
• Both files are rewritten on every create and recreate. Their content is a pure function of the mode, which is what makes an unconditional rewrite idempotent, and it means a credential change on the host is picked up by a recreate instead of leaving stale config behind. The flip side, inherited from the built-in agent this kit replaces: anything Codex wrote into config.toml during a previous session — project trust decisions, a /model choice — is discarded by a recreate. Only the truncating install hook does this; an ordinary stop/start leaves the file alone.

⁠MCP gateway

When a sandbox has an MCP gateway reserved, a startup hook appends an [mcp_servers.mcp-gateway] table to ~/.codex/config.toml pointing at it, with Authorization: Bearer $MCP_SENTINEL_TOKEN_NAME. The sentinel is a name, not a token — the proxy substitutes the real value per request, so nothing credential-shaped is ever written to disk.

Three details worth knowing if you edit that hook:

• The header table is http_headers, not headers. Codex ignores unknown config keys silently, so a headers table is accepted, the server shows up as registered and healthy, and every request through it goes out with no Authorization at all. headers is the right spelling for the JSON-configured agents in this repo (copilot, kiro); it does not carry over to Codex's TOML. codex mcp get mcp-gateway is the quick check — http_headers: Authorization=***** means it took.
• It appends. config.toml is shared territory: the install hook writes the yolo-mode and provider keys before launch, and Codex itself appends per-project and TUI state during a session. Rewriting the file would clobber both.
• It is guarded by grep on the table header, because startup hooks run on every container start — the initial create, every stop/start, and daemon restarts. Without the guard you would collect a duplicate table per boot.

With no gateway reserved, the hook exits 0 without touching anything.

⁠Related mixins

Two mixins in this repo declare requires: ["codex"], so they compose onto a kit that provides that name and nothing else:

• codex-acp⁠ — runs the Codex ACP adapter over stdio.
• codex-app-server⁠ — runs sshd so the Codex Mac GUI can drive codex app-server in the sandbox over an SSH connection.

sbx run ./codex/ --kit ./codex-acp/

Matching is by exact capability name, which is one reason this kit's directory and its provides entry are both plain codex rather than anything more descriptive. codex-mixin⁠ provides the same name, so both mixins compose onto it too — but never onto both kits at once, since one capability name has one owner.

⁠Credential exposure worth reviewing

The credential injects Authorization: Bearer <key> into api.openai.com and into the bare openai.com apex. The apex serves OpenAI's website, not the API — nothing observed from a live CLI needs a bearer token there — so any process in the sandbox that happens to fetch openai.com gets the real key attached on the way out. It is carried over from the built-in agent's spec unchanged, because a missing header is a silent 401 on whatever path did want it, and "no path wants it" is a negative this port cannot prove. There is a matching TODO on the entry in codex.yaml⁠; it should be dropped once someone can rule the last path out.

Note that v3 validates the other direction too: every inject domain must appear in the matching phase's allow list, so an inject rule the policy could never admit is now a build error rather than dead config.

⁠Network policy

The network-policy@1 capability's runtime.allow list covers every domain the credential injects into or authenticates against, the hosts Codex reaches during a session (uploads, codex update re-running the standalone installer, GitHub release checks and skill downloads), and the apt sources the base image ships with — the last of those because the startup hook runs apt-get update, which fails wholesale if any configured source is unreachable.

Everything sits in the runtime phase and the install phase is absent, which grants nothing there. That is not an oversight: v3 scopes egress by phase and closes the install grants before the entrypoint starts, and this kit's only install hook writes config files without opening a socket. The apt mirrors need a runtime grant because the hook that uses them is a startup hook, and startup hooks run at boot.

Two entries are wildcarded rather than exact: *.chatgpt.com and *.oaiusercontent.com. Live testing surfaced ChatGPT-backed content and auth traffic landing on subdomains of both rather than the bare apex, and OpenAI shards this across a set that isn't fixed or enumerable, so the wildcard is deliberate here — unlike the *.githubusercontent.com case below, which is left out because it has not been confirmed to be needed at all.

Hosts are listed without a port qualifier. The built-in agent's spec pinned :443 and :80; this kit does not, matching the other kits in this repo. On the apt mirrors in particular a hardcoded :80 would break apt-get update the day the base image's sources switch to https, and which scheme those sources use is not something this kit owns.

⁠Base image

Unlike a mixin, which layers onto whatever it lands on, a kind: workload kit is the whole environment: its layers are the sandbox's root filesystem and its image config carries the launch contract. So this kit builds that filesystem itself, from codex.dockerfile⁠ beside the descriptor.

The recipe builds on docker/sandbox-templates:shell-docker, so the result carries a Docker engine and requests Docker-in-Docker.

There is one artifact rather than two. Under v2 this kit named a separately published docker.io/sbx/codex-image in sandbox.image and the kit itself shipped as docker.io/docker/sbx-kit-codex; a v3 kit is one OCI image carrying both the declarations (in a manifest annotation) and the content (in its layers), so the published kit is the image the sandbox boots. The name is derived from the kit directory and enforced repo-wide — see PUBLISHING.md⁠.

There is no flavour suffix and no dockerless variant. The sandbox templates distinguish codex from codex-docker because a user picks a template directly, but a kit picks its own base — so the Docker-in-Docker detail never reaches the user, just as sbx run codex already resolves to the Docker flavour today. And a workload kit has exactly one content recipe, so a second image would be unreachable without a second kit to consume it.

⁠Building and publishing

How the image is named, tagged, verified and pushed is the same for every kit in this repo that builds its own image — see PUBLISHING.md⁠ for the pipeline, the tagging scheme, the coordinates, and the Docker Hub OIDC setup. Only the codex-specific parts are below.

⁠Building locally

docker build -f codex/codex.dockerfile -t docker.io/docker/sbx-kit-codex:latest codex

That builds the content alone. To build the kit — content plus the validated, expanded descriptor in its manifest annotation — build codex.yaml⁠ instead, which its # syntax=docker/sandbox-kit:3 line dispatches to the kit frontend:

docker build -f codex/codex.yaml -t docker.io/docker/sbx-kit-codex:latest codex

Codex installs via its standalone installer script, which downloads a platform-matched native binary and verifies it against a signed SHA-256 manifest — the path OpenAI's own docs lead with over the npm package. The build ends with codex --version so a broken install fails the image rather than shipping, and also symlinks the binary into the base image's npm global path for codex-app-server compatibility (see the note above).

BASE_IMAGE is a build arg, so the base can be re-pointed or digest-pinned without editing codex.dockerfile⁠: --build-arg BASE_IMAGE=… accepts a tag or a digest.