Codexbox

docker-codexbox

OpenAI Codex CLI inside an aicodebox container. Minimal and toolchain-loaded images, five ways in: interactive shell, one-shot exec, OpenAI-compatible endpoint, MCP server, Telegram bot, and a cron scheduler that fires codex on whatever schedule you want.

You talk to codexbox. codexbox talks to codex. codex talks to OpenAI — or your ChatGPT subscription. Nobody cares about the middle.

Table of Contents

• Quick start
• Using the codexbox wrapper
• Image variants
• Modes
• API mode
• Telegram mode
• Cron mode
• MCP mode
• Configuration
• Auth
• Agent integrations
• Development
• Tests
• License

Quick start

Docker installed and running is the only prerequisite.

One-liner install

The installer pulls the selected image, creates the persistent Codex and SSH directories, downloads the wrapper, and installs codexbox on your PATH.

# minimal image — default

curl -fsSL https://raw.githubusercontent.com/psyb0t/docker-codexbox/master/install.sh | bash

full image — every development tool pre-installed

export CODEXBOX_FULL=1 && curl -fsSL https://raw.githubusercontent.com/psyb0t/docker-codexbox/master/install.sh | bash

custom command name

curl -fsSL https://raw.githubusercontent.com/psyb0t/docker-codexbox/master/install.sh | bash -s -- codex

Installing with CODEXBOX_FULL=1 bakes latest-full into the wrapper, so the choice persists; you do not need to export it again. CODEXBOX_FULL must be set for bash, not merely for curl, hence the export … && form above.

Local checkout

From a checkout of this repository, build the matching image and install the local wrapper without pulling a published codexbox image:

make install       # minimal image

make install-full # full image

install only the local wrapper; do not build or pull

make install-wrapper CODEXBOX_FULL=1 make install-wrapper # full image

These targets set CODEXBOX_SRC_LOCAL=true. make install and make install-full build their image first; make install-wrapper only installs the local wrapper.sh against the selected existing image. It fails if that image is absent instead of falling back to docker pull.

The remote installer downloads wrapper.sh from its matching release tag. Automation can set CODEXBOX_INSTALL_DIR, CODEXBOX_BIN_NAME, and AICODEBOX_MANAGED_INSTALL=1 when it installs into a different command directory without prompting to replace an existing SSH key.

Using the codexbox wrapper

The wrapper mounts the current directory as the workspace, persists ~/.codex (so login survives container recreation), forwards auth and configured environment variables, and manages a per-directory container.

export OPENAI_API_KEY=sk-...         # or use a subscription: `codexbox login --device-auth`

codexbox # interactive TUI — continues the last session for THIS dir codexbox --no-continue # same, but starts a brand-new session instead codexbox exec "fix the failing test in ./app" # one-shot codex exec, output to your terminal echo "summarize README.md" | codexbox exec - # prompt via stdin codexbox login --device-auth # ChatGPT-subscription OAuth login (persists in ~/.codex) codexbox login status # which auth mode is active codexbox --version # passthrough to codex --version codexbox stop # stop this dir's running container(s) codexbox clear-session # drop codex's saved sessions (keeps auth + config)

The wrapper forwards "$@" straight to the image, so any codex subcommand works (codexbox mcp ..., codexbox doctor, etc.). The sandbox-bypass flag is injected inside the container — you never pass it yourself.

The bare interactive TUI defaults to continuing the most recent session for the directory you're in (same idea as claudebox's default) — codex's own resume --last cwd-scopes the lookup and starts a fresh session automatically when there's nothing to resume, so this is safe on a brand-new workspace too. Pass --no-continue to force a fresh session instead.

Install codexbox, claudebox, and pibox in the same command directory, normally /usr/local/bin, when one box needs to launch another. The wrapper finds sibling wrapper files there and mounts them read-only into the container. A sibling wrapper then runs through the host Docker daemon and mounts its own host data directory. Codexbox does not directly mount another agent's home.

Agent use and nested launches

The installed wrapper is the normal interface for people and agents. An agent should run codexbox from the requested workspace instead of assembling a new docker run command. The wrapper preserves the workspace path, Codex state, SSH state, image choice, and per-workspace container lifecycle.

codexbox exec "inspect this workspace and report the failing tests"

CODEXBOX_FULL=1 codexbox exec "run the full test suite" printf '%s\n' "summarize README.md" | codexbox exec -

When one box needs another, install codexbox, claudebox, and pibox in the same command directory. A running box can call the sibling command directly. The parent wrapper passes the host launch context and mounts only the sibling wrapper file. Do not set AICODEBOX_HOST_*, copy a wrapper, or manually mount another box's state directory.

The wrapper does not forward an SSH agent on its own. To give the box your agent, mount its socket and point SSH_AUTH_SOCK at it:

CODEXBOX_MOUNT_SSH="$SSH_AUTH_SOCK:/ssh-agent:ro" CODEXBOX_ENV_SSH_AUTH_SOCK=/ssh-agent codexbox

Every key loaded in that agent becomes usable inside the box.

Manual Docker use

Use raw Docker only for an explicitly requested container deployment. The wrapper is the normal route for interactive, one-shot, and local service use. The Modes section has the relevant deployment commands and configuration.

Image variants

• psyb0t/codexbox:latest is the default minimal image: Codex, Node.js, Python, uv, Docker, Git, jq, and curl.
• psyb0t/codexbox:latest-full starts from the shared aicodebox:latest-full base, then adds Codexbox's adapter, entrypoint, auth, and config.

CODEXBOX_FULL is binary: the installer defaults to minimal, 0 selects minimal, and 1 selects full. At runtime, an unset value preserves the installed image choice. Any other value fails. The installer writes the resolved image into the installed wrapper, so the choice persists without exporting the variable on every run. A runtime CODEXBOX_FULL=0 or CODEXBOX_FULL=1 temporarily forces a variant; CODEXBOX_IMAGE remains the highest-priority explicit override.

The full image adds:

• Go 1.27.2 with gopls, Delve, golangci-lint, staticcheck, gofumpt, and test/code-generation helpers
• Python 3.14.8 with pytest, Black, Flake8, mypy, Pyright, Poetry, Pipenv, and common HTTP/parsing libraries
• JavaScript and TypeScript linting, formatting, process, framework, API-test, static-server, Lighthouse, and Storybook CLIs
• GitHub CLI, Terraform, kubectl, and Helm
• Build tools, CMake, ClangFormat, Valgrind, GDB, strace, and ltrace
• PostgreSQL, MySQL, SQLite, and Redis clients
• Vim, Nano, tmux, htop, archive tools, network diagnostics, ripgrep, fd, bat, eza, shellcheck, and shfmt

The full variant inherits the shared Aicodebox full image. Aicodebox owns the shared toolchain pins, locks, and supply-chain checks. Codexbox adds only its agent package and startup layer.

Licensing note: the minimal image is clean — just Apache-2.0 Codex on top of the aicodebox base. The full image additionally bundles HashiCorp Terraform, which is BUSL-1.1 (source-available, non-compete), not OSI-approved open source. If that matters to your use case, stick to the minimal image or review the BUSL-1.1 terms yourself before using latest-full. Full breakdown in THIRD_PARTY.md.

Wrapper environment variables

Set CODEXBOX_GIT_NAME and CODEXBOX_GIT_EMAIL on the host to configure the runtime user's global Git identity before startup hooks. Direct container deployments accept the same names. Nonempty AICODEBOX_GIT_NAME and AICODEBOX_GIT_EMAIL inside the container take precedence; through the wrapper, supply those shared values as AICODEBOX_ENV_AICODEBOX_GIT_NAME and AICODEBOX_ENV_AICODEBOX_GIT_EMAIL. Empty settings preserve existing Git config. Multiline values are rejected.

make version V=X.Y.Z synchronizes package metadata, lockfile, the Codex plugin manifest, and the installer's wrapper release ref without committing or tagging. Remote installs download the matching release wrapper unless CODEXBOX_INSTALL_REF overrides it. Updating an image does not update an installed wrapper.

Set these on the host before running codexbox:

AICODEBOX_HOST_* is the versioned nested-launch context used by sibling wrappers. It records host bind-source paths and is set automatically by a wrapper. Do not set it for an ordinary host launch.

CODEXBOX_MODE_CRON=1 + CODEXBOX_MODE_CRON_FILE=/path/cron.yaml codexbox starts the cron scheduler as a long-running background container instead.

Prefer no host install? Everything the wrapper does is plain docker run; see Manual Docker use and Modes.

Modes

Foreground modes (API / Telegram / Cron) are mutually exclusive — except CODEXBOX_TELEGRAM_MODE=1 + CODEXBOX_CRON_MODE=1, which run together (cron in-thread inside telegram). API wins if set alongside anything else.

MCP mode (CODEXBOX_MCP_MODE=1) is independent — it coexists with whatever foreground mode is running. In API mode it's mounted at /mcp/ on the API port; in other modes it runs as a sidecar uvicorn on its own port.

Each