How to Run Headroom in Docker with the Official Container Image

You can deploy Headroom instantly by pulling the official image ghcr.io/chopratejas/headroom:latest, which packages the proxy service and exposes port 8787 for OpenAI-compatible LLM traffic.

The chopratejas/headroom repository maintains a multi-stage Dockerfile that compiles the Python wheels and native Rust core into a slim runtime image. Running Headroom in Docker eliminates the need to manage local Python dependencies or build tools, providing an isolated environment that handles compression, CCR (reversible compression), and content routing internally.

Pull the Official Image

The Headroom project publishes container images to the GitHub Container Registry. The image is built from the repository’s Dockerfile, which performs a multi-stage build to create a minimal runtime containing the headroom proxy entrypoint.

docker pull ghcr.io/chopratejas/headroom:latest

The image defaults to listening on 0.0.0.0:8787 and ships with a built-in health check that queries the /readyz endpoint to confirm service availability.

Run the Proxy with Docker

Basic Deployment

Start the container by mapping port 8787 to your host. The entrypoint defined in the image executes headroom proxy, which initializes the OpenAI-compatible compression gateway.

docker run -d \
  --name headroom-proxy \
  -p 8787:8787 \
  -e HEADROOM_HOST=0.0.0.0 \
  ghcr.io/chopratejas/headroom:latest \
  --host 0.0.0.0 --port 8787

• -p 8787:8787 binds the container’s proxy port to your local machine.
• -e HEADROOM_HOST=0.0.0.0 ensures the service accepts connections from outside the container.
• Arguments after the image name are passed directly to the headroom proxy command implemented in headroom/cli/proxy.py.

Connect to Custom Endpoints

To route requests to a non-standard OpenAI-compatible API (such as Azure OpenAI or a private deployment), set the OPENAI_TARGET_API_URL environment variable:

docker run -d \
  --name headroom-proxy \
  -p 8787:8787 \
  -e HEADROOM_HOST=0.0.0.0 \
  -e OPENAI_TARGET_API_URL=https://my.custom.api/v1 \
  ghcr.io/chopratejas/headroom:latest \
  --host 0.0.0.0 --port 8787

The proxy forwards all LLM calls to your specified URL while applying Headroom’s compression pipeline and cache alignment.

Docker Compose Configuration

For persistent development environments, use the docker-compose.yml file included in the repository root. This configuration defines the health check and networking explicitly.

services:
  headroom-proxy:
    image: ghcr.io/chopratejas/headroom:latest
    command: ["--host", "0.0.0.0"]
    environment:
      - HEADROOM_HOST=0.0.0.0
      # Uncomment to use a custom API endpoint

      # - OPENAI_TARGET_API_URL=https://api.x.ai

    ports:
      - "8787:8787"
    healthcheck:
      test: ["CMD", "curl", "--fail", "--silent", "http://127.0.0.1:8787/readyz"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 20s

Start the service with:

docker compose up -d
docker compose logs -f

You will see confirmation that the Headroom proxy is listening on 0.0.0.0:8787.

Verify the Deployment

Test the running container using the exposed port and the health endpoint:

curl http://localhost:8787/readyz

For a full integration test, send a chat completion request:

curl -X POST http://localhost:8787/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Hello"}]}'

A healthy container returns a compressed response from the downstream provider, confirming that the proxy is operational.

Summary

• The official image ghcr.io/chopratejas/headroom:latest is built from the repository’s multi-stage Dockerfile and packages the Rust core with a Python runtime.
• The default entrypoint runs headroom proxy on port 8787, exposing an OpenAI-compatible HTTP API.
• Configure OPENAI_TARGET_API_URL to route traffic to custom LLM endpoints.
• The container includes a health check against /readyz for orchestration platforms.
• Reference the included docker-compose.yml for production-ready deployment templates.

Frequently Asked Questions

What is the default port for the Headroom Docker container?

The container exposes the proxy service on port 8787 by default. This is configured in the Dockerfile entrypoint and can be overridden using the --port argument or by changing the port mapping in your docker run command.

How do I point Headroom to a different LLM API endpoint?

Set the OPENAI_TARGET_API_URL environment variable when starting the container. This variable directs the proxy to forward requests to your specified base URL instead of the default OpenAI endpoint, enabling compatibility with Azure OpenAI, X.AI, or private API gateways.

How can I check if the Headroom container is healthy?

The official image includes a Docker health check that executes curl --fail --silent http://127.0.0.1:8787/readyz every 30 seconds. You can also query this endpoint manually from the host to verify that the compression service is ready to accept connections.

Can I build the Docker image from source instead of using the official registry?

Yes. Clone the chopratejas/headroom repository and run docker build -t headroom:local . from the root directory. The Dockerfile handles compilation of the native Rust components and Python wheels, producing an image functionally identical to the ghcr.io distribution.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}