Codex

This guide covers authentication, configuration, and usage of Codex in a sandboxed environment.

Official documentation: Codex CLI

Quick start

Create a sandbox and run Codex for a project directory:

$ sbx run codex ~/my-project

The workspace parameter is optional and defaults to the current directory:

$ cd ~/my-project
$ sbx run codex

Authentication

If you haven't stored an OpenAI credential, sbx run codex prompts you to authenticate on your host before launching the sandbox. The flow runs on the host, so credentials are never exposed inside the sandbox.

To set up authentication ahead of time, choose one of the following methods.

OAuth: Start the OAuth flow on your host with:

$ sbx secret set -g openai --oauth

This opens a browser window for authentication and stores the resulting tokens in your OS keychain. The OAuth flow runs on the host, not inside the sandbox, so browser-based authentication works without any extra setup.

API key: Store your OpenAI API key using stored secrets:

$ sbx secret set -g openai

Alternatively, export the OPENAI_API_KEY environment variable in your shell before running the sandbox.

See Credentials for more details.

Configuration

Sandboxes don't pick up user-level configuration from your host, such as ~/.codex. Only project-level configuration in the working directory is available inside the sandbox. See Why doesn't the sandbox use my user-level agent configuration? for workarounds.

Default startup command

Without extra args, the sandbox runs:

codex --dangerously-bypass-approvals-and-sandbox

Args after -- replace these defaults rather than being appended. To keep the flag, include it yourself:

$ sbx run codex -- --dangerously-bypass-approvals-and-sandbox "fix the build"

Base image

Template: docker/sandbox-templates:codex

See Customize to pre-install tools or customize this environment.