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.

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.

Manual Docker use

Use raw Docker only when you intentionally do not want the wrapper, such as a one-shot run or a long-running API service. The Modes section has the relevant 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 adds the general-purpose development toolchain from Claudebox's full image while retaining Codexbox's own adapter, entrypoint, auth, and config.

CODEXBOX_FULL is binary: unset or 0 selects minimal; 1 selects full. 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.26.7 with gopls, Delve, golangci-lint, staticcheck, gofumpt, and test/code-generation helpers
• Python 3.14.7 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 is reproducible by design: its minimal parent and the published aicodebox parent are digest-pinned; Node tools install through a committed pnpm lockfile with lifecycle scripts disabled; Python tools install from a committed hash-locked requirements file; and Go tools build from a committed go.sum with the checksum database enabled. The lock inputs use a fixed seven-day release-age cutoff and are refreshed deliberately, not during an ordinary image build.

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 these on the host before running codexbox:

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 mode has its own page with full setup, env vars, and examples.

API Mode →

Long-lived FastAPI server on :8080. Agent runs (sync, async with run-id polling, cancellable), workspace file upload/download/list/delete with traversal checking, and an OpenAI-compatible chat/completions endpoint with streaming and client-executed tool calling. Codex's native --output-schema backs jsonSchema, so schema-conforming output needs no retries.

environment:
  - CODEXBOX_API_MODE=1
  - CODEXBOX_API_MODE_TOKEN=your-secret
  - CODEXBOX_AVAILABLE_MODELS=gpt-5.1-codex,gpt-5.1-codex-mini

Telegram Mode →