# How to Run Headroom in Docker with the Official Container Image > Easily run Headroom in Docker using the official container image ghcr.io/chopratejas/headroom:latest. Deploy the proxy service instantly and expose port 8787 for LLM traffic. - Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom) - Tags: how-to-guide - Published: 2026-06-05 --- **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. ```bash 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. ```bash 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`](https://github.com/chopratejas/headroom/blob/main/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: ```bash 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`](https://github.com/chopratejas/headroom/blob/main/docker-compose.yml) file included in the repository root. This configuration defines the health check and networking explicitly. ```yaml 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: ```bash 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: ```bash curl http://localhost:8787/readyz ``` For a full integration test, send a chat completion request: ```bash 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`](https://github.com/chopratejas/headroom/blob/main/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.