---
type: note
topic: Headroom Setup with Podman, OMP, and Codex
date: 2026-09-05
tags:
  - headroom
  - podman
  - omp
  - codex
  - ai-tools
  - token-compression
---

# Headroom with Podman, OMP, and Codex

Guide for running and managing **Headroom** (context compression & token optimization layer) on Windows using **Podman** (instead of Docker), and configuring both **OMP (Oh My Pi)** and **Codex** to route through it.

---

## 1. Overview & Architecture

[Headroom](https://github.com/headroomlabs-ai/headroom) compresses LLM prompts, tool outputs, logs, AST-parsed code, and RAG chunks before sending them to the model (saving 20%–90% of tokens while preserving accuracy).

```
AI Agent (OMP / Codex)
        │
        ▼ (Local request)
┌────────────────────────────────────────┐
│  Headroom Proxy (Port 8787)           │
│  - SmartCrusher (JSON)                 │
│  - CodeCompressor (AST-aware)          │
│  - Live-zone compression               │
│  - CCR (Reversible cache recovery)     │
└────────────────────────────────────────┘
        │
        ▼ (Compressed request)
LLM Provider (Anthropic / OpenAI API)
```

---

## 2. Managing Headroom with Podman

Podman is a daemonless, rootless drop-in replacement for Docker on Windows (powered by WSL2).

### Running the Container
To run Headroom as a background container with port 8787 forwarded:

```powershell
podman run -d `
  --name headroom `
  --restart always `
  -p 8787:8787 `
  -e HEADROOM_HOST=0.0.0.0 `
  -e HEADROOM_BEACON=off `
  ghcr.io/headroomlabs-ai/headroom:latest
```

> [!TIP]
> In WSL2 environments, if port forwarding to `localhost:8787` experiences issues, running with `--network host` binds directly to the Podman machine interface:
> ```powershell
> podman run -d --name headroom --network host -e HEADROOM_HOST=0.0.0.0 -e HEADROOM_BEACON=off ghcr.io/headroomlabs-ai/headroom:latest
> ```

### Verification & Health Check
Verify the proxy is running and responding:

```powershell
curl.exe http://localhost:8787/health
```
A healthy response returns `{"service":"headroom-proxy","status":"healthy", ...}`.

### Essential Podman Management Commands

| Task | Command |
| :--- | :--- |
| **Check container status** | `podman ps` |
| **View live logs** | `podman logs -f headroom` |
| **Restart container** | `podman restart headroom` |
| **Stop container** | `podman stop headroom` |
| **Start existing container** | `podman start headroom` |
| **Delete container** | `podman rm -f headroom` |

*(You can also manage the container visually inside **Podman Desktop** under the **Containers** tab).*

### Docker Alias (Optional)
If any external scripts or documentation invoke `docker`, alias it in PowerShell:

```powershell
Set-Alias -Name docker -Value podman
```

---

## 3. Using Headroom with OMP (Oh My Pi)

OMP routes LLM calls either via provider-specific base URL environment variables or through its configuration file.

### Method A: Environment Variables (Per Session)

#### For Anthropic / Claude Models:
```powershell
$env:ANTHROPIC_BASE_URL = "http://localhost:8787"
omp
```

#### For OpenAI / OpenAI-Compatible Models:
```powershell
$env:OPENAI_BASE_URL = "http://localhost:8787/v1"
omp
```

### Method B: Persistent OMP Configuration
In your OMP configuration directory (typically `~/.omp/config.json` or `models.yaml`):

```yaml
# models.yaml example
providers:
  openai:
    base_url: "http://localhost:8787/v1"
  anthropic:
    base_url: "http://localhost:8787"
```

### Method C: Direct Agent Wrap (When using Native CLI)
If the native `headroom` CLI is installed:
```powershell
headroom wrap omp
```
To unwrap when finished:
```powershell
headroom unwrap omp
```

---

## 4. Using Headroom with Codex

Codex communicates with OpenAI-compatible endpoints.

### Method A: Environment Variable (CLI / Terminal)
Before launching Codex, point the OpenAI base URL to Headroom:

```powershell
$env:OPENAI_BASE_URL = "http://localhost:8787/v1"
codex
```

### Method B: Direct Agent Wrap (Native CLI)
If you have the native `headroom` CLI:
```powershell
headroom wrap codex
```

### Method C: Model Context Protocol (MCP) Integration
If using Codex in an MCP-aware client or editor, register Headroom as an MCP server:

```json
{
  "mcpServers": {
    "headroom": {
      "command": "headroom",
      "args": ["mcp", "serve"]
    }
  }
}
```

---

## 5. Alternative: Native Windows Setup (Zero Containers)

Headroom is distributed as a standard Python package. Because **Python 3.11** and **`uv`** are installed on Windows, you can bypass containers completely:

### Install via `uv`
```powershell
uv tool install "headroom-ai[all]"
```

### Launch Proxy or Wrap Agents
```powershell
# Run the proxy:
headroom proxy --port 8787

# Check system health:
headroom doctor

# View savings dashboard:
headroom dashboard
```

---

## 6. Monitoring Token Savings & Stats

Once requests are flowing through Headroom:

- **Health Endpoint:** `http://localhost:8787/health`
- **Detailed Stats:** `http://localhost:8787/stats`
- **Historical Savings:** `http://localhost:8787/stats-history`
- **Prometheus Metrics:** `http://localhost:8787/metrics`

Check container logs in real time to observe live compression ratios and token counts:
```powershell
podman logs -f headroom
```

---

## 7. Automated Launcher Script (`launch-headroom.ps1`)

An automated PowerShell launcher script is available at `C:\Users\Hamza\launch-headroom.ps1` (and mirrored in `Documents\PowerShell\Scripts\launch-headroom.ps1`).

### What It Does Automatically
1. **Podman Check:** Verifies Podman CLI and boots the Podman WSL machine if stopped (`podman machine start`).
2. **Container Management:** Starts or creates the `headroom` container.
3. **Smart Network Routing:** Auto-detects whether to use `localhost:8787` or the WSL IP (`172.20.177.183:8787`).
4. **Dashboard:** Automatically opens the live Headroom web dashboard in your default browser.
5. **Agent Configuration:** Sets required base URLs and launches your chosen AI agent.

### Command Reference Table

| Goal | Alias Command | Full Script Path |
| :--- | :--- | :--- |
| **Interactive Start** (shows menu) | `headroom-start` | `.\launch-headroom.ps1` |
| **Direct Codex Launch** | `headroom-start -Agent codex` | `.\launch-headroom.ps1 -Agent codex` |
| **Direct OMP Launch** | `headroom-start -Agent omp` | `.\launch-headroom.ps1 -Agent omp` |
| **Proxy Only** (no agent launched) | `headroom-start -Agent none` | `.\launch-headroom.ps1 -Agent none` |
| **Stop Headroom** | `headroom-stop` | `.\launch-headroom.ps1 -Stop` |

### Detailed Execution Examples

#### 1. Via PowerShell Alias (Any Terminal)
Because `headroom-start` and `headroom-stop` are configured in your `$PROFILE`:
```powershell
# Launch interactively (opens dashboard and asks for Codex/OMP/Stop):
headroom-start

# Directly launch Codex through Headroom proxy:
headroom-start -Agent codex

# Directly launch OMP (Oh My Pi) through Headroom proxy:
headroom-start -Agent omp

# Start proxy in background without launching an agent:
headroom-start -Agent none

# Stop the running Headroom container:
headroom-stop
```

#### 2. Via Direct File Path
From your home directory or where the script lives:
```powershell
# Interactive mode:
& "$HOME\launch-headroom.ps1"

# With arguments:
& "$HOME\launch-headroom.ps1" -Agent codex
& "$HOME\launch-headroom.ps1" -Agent omp
& "$HOME\launch-headroom.ps1" -Stop
```

#### 3. From Windows Run Dialog (Win + R) or Shortcut
```cmd
powershell.exe -ExecutionPolicy Bypass -NoExit -File "%USERPROFILE%\launch-headroom.ps1"
```

---

## Related Notes

- [[04 Knowledge/Knowledge Index]]
- [[Agent Reach Notes]]
- [[04 Knowledge/Docker Organization Comparison]]
- [[04 Knowledge/Claude code]]