docker-codexbox

# docker-codexbox

[![Docker Pulls](https://img.shields.io/docker/pulls/psyb0t/codexbox?style=flat-square)](https://hub.docker.com/r/psyb0t/codexbox)
[![License: WTFPL](https://img.shields.io/badge/License-WTFPL-brightgreen.svg?style=flat-square)](http://www.wtfpl.net/)

[OpenAI Codex CLI](https://github.com/openai/codex) inside an [aicodebox](https://github.com/psyb0t/docker-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](#quick-start)
- [Using the `codexbox` wrapper](#using-the-codexbox-wrapper)
- [Image variants](#image-variants)
- [Modes](#modes)
  - [API mode](#api-mode)
  - [Telegram mode](#telegram-mode)
  - [Cron mode](#cron-mode)
- [Configuration](#configuration)
- [Auth](#auth)
- [Development](#development)
- [Tests](#tests)
- [License](#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`.

```bash
# 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.

## 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.

```bash
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](#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.1 with gopls, Delve, golangci-lint, staticcheck, gofumpt, and test/code-generation helpers
- Python 3.12.11 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](https://github.com/hashicorp/terraform/blob/main/LICENSE)
yourself before using `latest-full`. Full breakdown in
[THIRD_PARTY.md](THIRD_PARTY.md).

### Wrapper environment variables

Set these on the host before running `codexbox`:

| Var | Default | What it does |
|-----|---------|---------------|
| `OPENAI_API_KEY` | — | API-key auth (seeded into `~/.codex/auth.json` on boot). Not needed for subscription login. |
| `OPENAI_BASE_URL` | — | Point codex at an OpenAI-compatible endpoint |
| `CODEXBOX_IMAGE` | installed image | Override the image the wrapper runs |
| `CODEXBOX_FULL` | installed choice (`0` initially) | `0` forces minimal; `1` forces full |
| `CODEXBOX_DATA_DIR` | `~/.codex` | Host dir mounted as `CODEX_HOME` (auth + config + sessions) |
| `CODEXBOX_SSH_DIR` | `~/.ssh/codexbox` | SSH key dir mounted into the container (for git over SSH) |
| `CODEXBOX_MAX_MEM` | `10g` | Per-container memory limit |
| `CODEXBOX_CONTAINER_NAME` | derived from `$PWD` | Override the per-workspace container name |
| `CODEXBOX_ENV_*` | — | Forward arbitrary env into the container (prefix stripped: `CODEXBOX_ENV_FOO=bar` → `FOO=bar`) |
| `CODEXBOX_MOUNT_*` | — | Mount extra host dirs (`/host:/container` syntax, or a bare path for same-path-both-sides) |

`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](#manual-docker-use) and [Modes](#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.

### API mode

`CODEXBOX_API_MODE=1`. FastAPI server on `:8080` (override with `CODEXBOX_API_MODE_PORT`).

> **Required:** `CODEXBOX_AVAILABLE_MODELS=<csv>` (e.g. `gpt-5.1-codex,gpt-5.1-codex-mini`). API mode refuses to boot without it — `/openai/v1/models` needs a real list and there's no sensible default (codex has no hardcoded model slug; it's server-driven and OpenAI can add/retire models without notice).

| Method | Path | What it does |
|--------|------|--------------|
| `GET` | `/healthz` | liveness |
| `GET` | `/status` | in-flight runs |
| `POST` | `/run` | sync agent run → `{runId, workspace, exitCode, text, ...}`; pass `"async": true` in the body to fire and get a `runId` back instead |
| `GET` | `/run/result?runId=<id>` | poll async job |
| `DELETE` | `/run/{run_id}` | kill in-flight run |
| `GET` | `/files` | list the workspace root (`{entries: [{name, type, size?}, ...]}`) |
| `GET` | `/files/{path}` | list a sub-directory, or stream a file's bytes |
| `PUT` | `/files/{path}` | upload — raw request body becomes the file contents; parent dirs auto-created |
| `DELETE` | `/files/{path}` | delete a file (refuses directories — 400) |
| `POST` | `/openai/v1/chat/completions` | OpenAI-compatible (streaming + non-streaming; supports `tools` / `tool_choice` client-executed tool calling, composable with `response_format`) |
| `GET` | `/openai/v1/models` | model list |
| `POST` | `/mcp` | MCP server (streamable HTTP) — mounted only when `CODEXBOX_MCP_MODE=1` |

All `/files/*` paths are resolved against the workspace root with traversal checking — `..` segments that escape the root return 400. Same `Authorization: Bearer ...` token gates them as the rest of the API.

```bash
# upload a file
curl -sS -X PUT \
  -H "Authorization: Bearer your-secret" \
  --data-binary @local.txt \
  http://localhost:8080/files/notes/hello.txt

# download it back
curl -sS -H "Authorization: Bearer your-secret