Copy .env.example to .env and set TELEGRAM_BOT_TOKEN, HOST_CODEX_SOCKET, HOST_CODEX_RUN_DIR, HOST_UPLOAD_DIR, HOST_CODEX_HOME, and HOST_PLAYGROUND_DIR.
Start the host Codex app-server:
```
scripts/start-codex-app-server start
```
The script supports start, stop, status, check-updates [-y], and the alias check-upgrade [-y]. start launches Codex detached, writes run/codex-app-server.pid, logs to run/codex-app-server.log, and is idempotent if the socket is already live. check-updates compares the local codex binary with the latest OpenAI Codex GitHub release. With -y, it downloads and validates the matching platform archive before stopping a running app-server. If the app-server is running, the final stop/replace/start step is handed to a detached worker so the upgrade can complete even when invoked from Codex itself. If the upgraded server fails to start, the worker restores the previous binary and starts it again.

Add at least one Telegram user and workspace:

scripts/allow-user 123456789 username
scripts/add-workspace "$PWD" "Workspace name" --default

Build the bot binary when source changes:
```
scripts/build-bot
```
Start or restart the bot without rebuilding:
```
docker compose up -d
```
For normal restarts, use docker compose restart bot. The container runs ./bin/codex-telegram-bot mounted read-only into Alpine; Compose does not compile Go code.

Commands

The bot accepts one-to-one chats from allowlisted Telegram user IDs only. It rejects group, supergroup, and channel updates in code.

Supported commands: /start, /help, /new, /threads, /resume, /rename, /fork, /archive, /status, /cancel, /workspaces, /workspace, /model, /sandbox, /pic, /diff. /model lists available Codex models as inline buttons, then shows reasoning-effort buttons for the selected model.

Plain text continues the active Codex thread and creates one if needed. /pic PROMPT starts a dedicated Codex image-generation turn and sends generated images back as Telegram photos. Telegram images are staged under HOST_UPLOAD_DIR and sent as localImage inputs. Other uploaded documents are staged and passed to Codex as host-visible file paths.

Notes

HOST_UPLOAD_DIR must be the same absolute path inside the bot container and on the host so host Codex can read staged files.
HOST_CODEX_SOCKET must point to the host app-server socket. HOST_CODEX_RUN_DIR is mounted into the bot container at the same absolute path so socket recreation is visible without rebuilding.
HOST_PLAYGROUND_DIR should point to the shared playground/workspace root mounted at the same absolute path, so assistant photo directives can reference workspace-local image files that the bot container can read.
Use long polling for the MVP; webhooks are not required.