How to Run Headroom Using the Official Docker Container Image

Pull the official image ghcr.io/chopratejas/headroom:latest and execute docker run -p 8787:8787 -e HEADROOM_HOST=0.0.0.0 ghcr.io/chopratejas/headroom:latest --host 0.0.0.0 --port 8787 to start the LLM proxy service on port 8787 with built-in health checks.

Headroom provides a production-ready Docker image that packages the proxy service with its native Rust core and Python runtime. This guide explains how to run Headroom using the official Docker container image published by the chopratejas/headroom repository, which exposes an OpenAI-compatible API endpoint for compression and caching without requiring client-side modifications.

Pulling the Official Docker Image

The Headroom project publishes multi-stage container images to the GitHub Container Registry. The Dockerfile in the repository root compiles Python wheels (including the native Rust core) and packages them into a slim Python runtime with an optional distroless variant.

docker pull ghcr.io/chopratejas/headroom:latest

Running the Container with Docker Run

The container entrypoint is configured to execute headroom proxy as specified in the Dockerfile. When the container starts, it binds to 0.0.0.0:8787 by default and exposes a health-check endpoint at /readyz that confirms the service is ready to accept traffic.

Execute the following command to run the proxy with standard configuration:

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

This command maps port 8787 from the container to your host, sets the HEADROOM_HOST environment variable to bind to all network interfaces, and passes the --host and --port arguments to the headroom proxy entrypoint defined in headroom/cli/proxy.py.

Configuring Custom API Endpoints

You can route requests to non-standard OpenAI-compatible endpoints (such as Azure OpenAI or X.AI) by setting the OPENAI_TARGET_API_URL environment variable. The proxy forwards all LLM calls to the specified URL while applying Headroom’s compression pipeline.

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

Deploying with Docker Compose

For development environments, use the docker-compose.yml file provided in the repository root. The compose configuration includes a health check that queries http://127.0.0.1:8787/readyz using curl to verify service availability.

Create a docker-compose.yml with the following content:

services:
  headroom-proxy:
    image: ghcr.io/chopratejas/headroom:latest
    command: ["--host", "0.0.0.0"]
    environment:
      - HEADROOM_HOST=0.0.0.0
      # Uncomment to point at 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 stack:

docker compose up -d
docker compose logs -f

The logs will display "Headroom proxy listening on 0.0.0.0:8787" when the container is ready to accept connections.

Verifying the Proxy Deployment

Test the running container by sending a chat completion request to verify the proxy is forwarding requests correctly:

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 LLM provider.

Summary

• The official image ghcr.io/chopratejas/headroom:latest is built from the repository’s Dockerfile with a multi-stage build process including the Rust core and Python wheels
• The container entrypoint executes headroom proxy and listens on 0.0.0.0:8787 by default, with health checks available at /readyz
• Use the -e OPENAI_TARGET_API_URL environment variable to route requests to custom OpenAI-compatible endpoints
• The docker-compose.yml in the repository provides a production-ready template with automated health checks using curl against the internal endpoint

Frequently Asked Questions

How do I change the default port when running Headroom in Docker?

Modify the port mapping and command arguments in your docker run command. Map -p 8080:8080 to expose a different host port and append --port 8080 to the container arguments. The proxy service will bind to the new port internally while remaining accessible externally via your mapped port.

What is the purpose of the HEADROOM_HOST environment variable?

The HEADROOM_HOST variable controls the network interface binding inside the container. Setting it to 0.0.0.0 is required for Docker deployments because it allows the proxy to accept connections from outside the container. Without this setting, the service would only listen on localhost within the container, making it inaccessible from the host machine.

Can I use the Headroom Docker image with Azure OpenAI Service?

Yes. Set the OPENAI_TARGET_API_URL environment variable to your Azure OpenAI endpoint URL when starting the container. The proxy will forward all requests to that URL while maintaining its compression and caching functionality. Point your OpenAI client to the Headroom proxy address (http://localhost:8787) without modifying any other client configuration.

How do I check if the Headroom container is running correctly?

Query the health-check endpoint at http://localhost:8787/readyz using curl or check the container logs for the listening message. The Docker Compose configuration includes an automated health check that runs every 30 seconds, marking the container as healthy when the service responds successfully.

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