Codexbox MCP server

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

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 CODEXBOXFULL=1 bakes latest-full into the wrapper, so the choice persists; you do not need to export it again. CODEXBOXFULL 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 CODEXBOXSRCLOCAL=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 CODEXBOXINSTALLDIR, CODEXBOXBINNAME, and AICODEBOXMANAGEDINSTALL=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`

Shortened. The full README is on GitHub.