Skip to main content
Codex ships its own sandbox for model-generated commands, and its most permissive switch is documented as “intended solely for running in environments that are externally sandboxed”. A box is exactly that environment.

Prerequisites

  • The boxlite Python package and a machine with hardware virtualization — see Installation.
  • An OpenAI API key, or a ChatGPT plan you can log into.
  • A glibc-based image. Codex publishes prebuilt binaries as optional dependencies for linux-x64 and linux-arm64 only. node:20-slim is verified working: installed inside a box in about 22 s, after which codex --version reports codex-cli 0.147.0. Musl images such as node:alpine have no matching binary.
  • System CA certificates in the image. Slim images ship without them, and Codex needs them to reach any API over TLS. Install ca-certificates before the first prompt — the Quick Example does this in step 1. See Why a slim image needs ca-certificates for why this failure is easy to misdiagnose.

Quick Example

Install the CLI, authenticate from stdin, and run one non-interactive prompt.
Verified inside a box on macOS (Apple Silicon) against an OpenAI-compatible endpoint. codex exec echoes the exchange, then repeats the final answer:

Why a slim image needs ca-certificates

This one is worth knowing in advance, because the symptom points away from the cause. node:20-slim has no /etc/ssl/certs/ca-certificates.crt. Codex is a Rust binary that verifies TLS against the system trust store, so with no root certificates every model call dies at the handshake — surfacing as a transport error such as stream disconnected before completion, which reads like a network or endpoint problem rather than a missing file. Two things make it easy to misdiagnose:
  • npm install still works. Node ships its own bundled CA store, so installing the CLI and running codex --version both succeed. The failure appears only at the first prompt, long after the step that would have revealed it.
  • Installing curl to test connectivity hides the problem. ca-certificates is a dependency of curl, so the moment you install a tool to check the network, you have silently fixed the thing you were trying to diagnose — and the network test passes.
Confirm it directly instead of inferring it from a failed request:
Images that already include the certificates — node:20 (not -slim), debian, ubuntu — need no extra step. This applies to any agent CLI compiled as a native binary, not only Codex.

Parameters and Returns

From codex --help and codex exec --help:

Two sandboxes, one decision

Codex sandboxes the commands its model generates, and BoxLite sandboxes the whole Codex process. Inside a box the inner sandbox is redundant for containment — the VM boundary already holds — so you can relax it and let the agent work without per-action prompts:
Relaxing it means the agent can do anything the box can do. That is the point of running it in a box, and it is also why the box’s own boundary matters: keep the network narrow and the credential outside if the task is not fully trusted — see Secrets and hardening. If you would rather keep Codex’s own sandbox on, pass -s workspace-write instead and leave the bypass flag off.

Keeping the API key out of the box

Piping the key through codex login --with-api-key keeps it off the command line, but it still enters the sandbox. To keep the real value on the host, inject it at the proxy: the box sees a placeholder, and BoxLite substitutes the real value on outbound requests to the hosts you allow.
Substitution covers request headers, the URL query string, and the request body — not the URL path.

Troubleshooting

  • Run Pi — a CLI whose custom endpoints go through a config file rather than environment variables.
  • Run Claude Code — the same pattern, plus SkillBox and a noVNC desktop.
  • Run untrusted tools safely — narrowing network and privileges around an agent you do not trust.