Sign inSign up

psyb0t/codexbox

By psyb0t

•Updated 8 days ago

OpenAI Codex CLI in a Docker image built on aicodebox, with an HTTP API, an OpenAI-compatible end...

Image
0

10K+

psyb0t/codexbox repository overview

Source⁠ | Project page⁠

⁠codexbox

CI version license Docker Pulls

OpenAI Codex CLI⁠ inside an aicodebox⁠ container. Minimal and toolchain-loaded images, and six ways in: interactive shell, one-shot exec, an HTTP API with an OpenAI-compatible endpoint, an MCP server, a 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 to your ChatGPT subscription. Nobody cares about the middle.

Documentation: https://psyb0t.github.io/docker-codexbox/⁠

⁠Table of Contents

⁠Quick start

Docker installed and running is the only prerequisite. The installer pulls the image, creates ~/.codex and ~/.ssh/codexbox, and installs the codexbox command on your PATH.

# minimal image, the default
curl -fsSL https://raw.githubusercontent.com/psyb0t/docker-codexbox/main/install.sh | bash

# full image, every development tool installed
export CODEXBOX_FULL=1 && curl -fsSL https://raw.githubusercontent.com/psyb0t/docker-codexbox/main/install.sh | bash

Then log in once and go:

codexbox login --device-auth                     # ChatGPT subscription, or: export OPENAI_API_KEY=sk-...
codexbox                                         # Codex TUI, continuing the last session for THIS directory
codexbox --no-continue                           # same, but a brand-new session
codexbox exec "fix the failing test in ./app"    # one-shot, output to your terminal
echo "summarize README.md" | codexbox exec -     # prompt via stdin
codexbox stop                                    # stop this directory's containers

The wrapper mounts the current directory, keeps ~/.codex so the login and sessions survive, and passes any other codex subcommand straight through. The sandbox-bypass flag is added inside the container; the container is the sandbox. Install routes, local builds and every wrapper setting are in Install⁠ and The codexbox wrapper⁠.

⁠Image variants

  • psyb0t/codexbox:latest: Codex, Node.js, Python, uv, Docker, Git, jq and curl, on psyb0t/aicodebox:v0.18.4.
  • psyb0t/codexbox:latest-full: the same Codex layer on psyb0t/aicodebox:v0.18.4-full, with Go, Python, JavaScript and TypeScript tooling, GitHub CLI, Terraform, kubectl, Helm, debuggers and database clients.

The full image bundles Terraform, which is BUSL-1.1 and not OSI-approved open source. The variant list and licensing notes⁠ have the details, and THIRD_PARTY.md⁠ lists every bundled component.

⁠Modes

Set a mode flag and the container becomes a service. API, Telegram and cron run in the foreground (API wins; Telegram and cron can run together). MCP runs next to any of them.

FlagWhat you get
CODEXBOX_API_MODE=1POST /run, workspace files over HTTP, and an OpenAI-compatible chat/completions endpoint on :8080. Needs CODEXBOX_AVAILABLE_MODELS.
CODEXBOX_TELEGRAM_MODE=1Codex in Telegram, one workspace per chat, per-chat /model and /effort
CODEXBOX_CRON_MODE=1YAML jobs on 6-field cron schedules, with run history
CODEXBOX_MCP_MODE=1run_prompt and workspace file tools over streamable HTTP
services:
  codexbox:
    image: psyb0t/codexbox:latest
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      - CODEXBOX_API_MODE=1
      - CODEXBOX_API_MODE_TOKEN=your-secret
      - CODEXBOX_AVAILABLE_MODELS=gpt-5.1-codex,gpt-5.1-codex-mini
      - OPENAI_API_KEY=sk-...
    volumes:
      - ~/workspaces:/workspace

An empty token means no auth on that surface. Each mode's page in the documentation⁠ has its settings and examples.

⁠Documentation

The full documentation lives at https://psyb0t.github.io/docker-codexbox/⁠.

SectionWhat it covers
Install⁠Installer, local builds, upgrading, image variants and licensing
The codexbox wrapper⁠Commands, host settings, CODEXBOX_ENV_ forwarding, sibling boxes, SSH agents
Authentication⁠API key or ChatGPT subscription, models and reasoning effort
Configuration⁠Container settings, AICODEBOX_ aliases, Git identity, init scripts, ports
Modes⁠API⁠, Telegram⁠, cron⁠ and MCP⁠
Codex adapter⁠How run options map to Codex flags, and session continuation
Agent integrations⁠The skill and plugins for Claude Code, Codex and OpenClaw
Troubleshooting⁠Error messages and their fixes
Development⁠Building, linting, testing, CI and releases

⁠Agent integrations

The skill⁠ works in any agent that reads .agents/skills/ (such as peen⁠) and installs natively in Claude Code, Codex and OpenClaw:

claude plugin marketplace add psyb0t/agents && claude plugin install codexbox@psyb0t
codex plugin marketplace add psyb0t/agents && codex plugin add codexbox@psyb0t
openclaw skills install @psyb0t/codexbox

The @psyb0t/codexbox⁠ OpenClaw plugin bridges stdio MCP clients to a running box. See Agent integrations⁠.

⁠Development

make help        # every target
make build       # minimal image on the published aicodebox base
make build-full  # full image
make lint        # shellcheck, shfmt, ruff and pyright, all in containers
make test-ci     # the credential-free tests CI runs
make test        # the end-to-end suite (needs .env.test)
make docs        # build the documentation site into .testing/docs-site

Details in Development⁠.

⁠Sponsor

Buy Me a Coffee

⁠License

WTFPL, see LICENSE⁠. Do what the fuck you want.

Third-party components bundled in the published images (Codex, and in the full image only Terraform, gh, kubectl, Helm and golangci-lint) keep their own licenses; see THIRD_PARTY.md⁠.

Tag summary

Content type

Image

Digest

sha256:22370fa2c…

Size

771.7 MB

Last updated

8 days ago

docker pull psyb0t/codexbox