Docker

Run tawa-codex-proxy as a local container — no Rust toolchain on the host, and an easy way to keep it always-on.

tawa-cli-proxy ships a Dockerfile.codex at the repo root — a separate file from the Claude Code relay's Dockerfile rather than a build-arg switch between the two, since they're different binaries with different default ports. Building it gives you a self-contained image with no Rust toolchain, cmake, nasm, or perl needed on the host — only Docker.

No image is published to a registry yet — there's no docker pull to run. You build it locally from source.

Build the image

From the tawa-cli-proxy repo root:

docker build -f Dockerfile.codex -t tawa-codex-proxy .

Same multi-stage shape as the Claude Code relay's image: a rust:1.90-slim-bookworm builder stage compiles a release binary with cargo build --release --locked -p tawa-cli-proxy-codex, then the binary is copied into a minimal debian:bookworm-slim runtime image running as a non-root user.

Run it

docker run -d \
  --name tawa-codex-proxy \
  -p 127.0.0.1:8788:8788 \
  -e TAWA_API_KEY=<your Tawa API key> \
  tawa-codex-proxy

Bind to loopback

-p 127.0.0.1:8788:8788 (not just -p 8788:8788) publishes the port to the host's loopback interface only. Omitting the 127.0.0.1: prefix publishes it on every network interface — this proxy has no authentication of its own beyond whatever key Codex CLI hands it, so exposing it beyond localhost on a laptop is a real risk, not a theoretical one.

The image sets TAWA_PROXY_LISTEN_ADDR=0.0.0.0:8788 by default (rather than the binary's own 127.0.0.1:8788 default — see Configuration). This has to be 0.0.0.0 inside the container, or Docker's own port-forwarding can't reach it — the -p 127.0.0.1:8788:8788 flag above is what actually restricts external access, not this setting.

Check it's up:

docker ps --filter name=tawa-codex-proxy
curl http://127.0.0.1:8788/healthz
# ok

The image also defines a HEALTHCHECK against /healthz, so docker ps/docker inspect report container health directly.

Point Codex CLI at it

Same as the source-build path — Codex CLI doesn't know or care whether what's listening on 127.0.0.1:8788 is a container or a native process:

export OPENAI_BASE_URL=http://127.0.0.1:8788/v1
export OPENAI_API_KEY=<your real OpenAI key>
codex

Configuration and logs

Pass any of the environment variables with -e:

docker run -d \
  --name tawa-codex-proxy \
  -p 127.0.0.1:8788:8788 \
  -e TAWA_API_KEY=<your Tawa API key> \
  -e TAWA_PROXY_FAIL_MODE=closed \
  -e RUST_LOG=debug \
  tawa-codex-proxy

docker logs -f tawa-codex-proxy

Keep it running

For a single laptop, --restart unless-stopped is usually enough so the proxy survives a reboot without a supervisor:

docker run -d \
  --name tawa-codex-proxy \
  --restart unless-stopped \
  -p 127.0.0.1:8788:8788 \
  -e TAWA_API_KEY=<your Tawa API key> \
  tawa-codex-proxy

For a shared, always-on setup instead of a single developer's machine, see VPS deployment.

Build the image

Run it

Point Codex CLI at it

Configuration and logs

Keep it running

On this page