# How to Run Headroom Using the Official Docker Container Image

> Easily run Headroom using the official Docker container. Get the LLM proxy service up and running on port 8787 with this simple Docker command. Includes health checks.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: how-to-guide
- Published: 2026-06-20

---

**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.

```bash
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:

```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

```

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`](https://github.com/chopratejas/headroom/blob/main/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.

```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

```

## Deploying with Docker Compose

For development environments, use the [`docker-compose.yml`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/docker-compose.yml) with the following content:

```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 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:

```bash
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:

```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 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`](https://github.com/chopratejas/headroom/blob/main/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.