# How to Set Up a Development Environment for Headroom: Complete Guide

> Easily set up your Headroom development environment. Clone the repo, create a Python virtual environment, install uv, sync dependencies, and install Headroom in editable mode. Get started today!

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: getting-started
- Published: 2026-06-21

---

**You can set up a development environment for Headroom by cloning the repository, creating a Python virtual environment, installing the `uv` package manager, syncing dependencies with `uv sync --extra dev`, and installing the package in editable mode with optional extras.**

Headroom is a multi-language compression layer for AI agents maintained in the `chopratejas/headroom` repository. The project combines a Rust core with Python bindings, requiring specific tooling for both languages. This guide walks through the exact steps to create a reproducible development setup using the officially supported `uv` workflow or the optional VS Code devcontainer.

## Prerequisites

Before you begin, ensure you have **Python 3.x** and **Git** installed on your system. The build system relies on a [`pyproject.toml`](https://github.com/chopratejas/headroom/blob/main/pyproject.toml) with a Maturin backend for the Rust core, though the Rust toolchain is handled automatically when you use `uv` for dependency management.

## Setting Up a Development Environment for Headroom

The repository organizes core Python code under `headroom/`, transform logic under `headroom/transforms/`, and provider-specific adapters under `headroom/providers/`. Follow these steps to build from source:

### Clone the Repository

Start by cloning the full source tree, which includes the Rust core, Python bindings, and documentation.

```bash
git clone https://github.com/chopratejas/headroom.git
cd headroom

```

### Create a Python Virtual Environment

Isolate your dependencies from the system Python to avoid conflicts.

```bash
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

```

### Install uv and Sync Dependencies

The Headroom project officially supports **uv**, an extremely fast Python package manager that also handles Rust toolchain requirements.

```bash
pip install -U uv
uv sync --extra dev

```

This command pulls in Python packages and the necessary Rust toolchain for building `headroom-core`.

### Install in Editable Mode

Install the package with development extras so you can import `headroom` locally and modify code without reinstallation.

```bash
uv pip install -e ".[dev,relevance,proxy]"

```

The extras `dev`, `relevance`, and `proxy` include testing utilities, relevance scoring capabilities, and the local proxy server respectively.

### Verify with Tests and Linting

Confirm your environment matches CI expectations by running the test suite and style checks.

```bash
uv run pytest
uv run ruff check .
uv run ruff format .

```

According to the [`CONTRIBUTING.md`](https://github.com/chopratejas/headroom/blob/main/CONTRIBUTING.md) guide, all pull requests must pass these checks before merge.

## Using the Devcontainer (Alternative Setup)

If you prefer a containerized environment, the repository includes a fully configured VS Code devcontainer defined in [`.devcontainer/devcontainer.json`](https://github.com/chopratejas/headroom/blob/main/.devcontainer/devcontainer.json).

- Open the repository in VS Code and run **Reopen in Container**
- The container pre-installs Node 20, Rust 1.95, and creates a persistent virtual-env volume
- Port **8787** is automatically forwarded for the Headroom proxy
- VS Code extensions for Python, Ruff, Docker, and GitHub Actions are pre-installed

This approach eliminates "works on my machine" issues by providing identical environments across macOS, Linux, and Windows.

## Running the Proxy Locally

Once your development environment is active, you can start the local compression proxy to intercept and compress AI agent traffic.

```bash
headroom proxy --port 8787

```

Other agents can now route through your local instance by setting `export HEADROOM_PROXY=http://localhost:8787`.

## Working with the Codebase

After setup, you can import and use the library directly in Python. The public API is exposed in [`headroom/__init__.py`](https://github.com/chopratejas/headroom/blob/main/headroom/__init__.py), specifically the `compress` function.

```python
from headroom import compress

messages = [
    {"role": "user", "content": "Explain the quicksort algorithm."}
]

compressed = compress(messages, model="gpt-4o")
print(compressed)

```

Key directories to explore:
- **`headroom/transforms/`** – Contains core transform implementations like `CacheAligner`, `ContentRouter`, and `SmartCrusher`
- **`headroom/providers/`** – Houses adapters for Claude, OpenAI, Bedrock, and other LLM providers
- **`tests/`** – The full test suite that validates compression logic and provider integrations

## Summary

- Headroom uses a hybrid Rust/Python architecture managed through [`pyproject.toml`](https://github.com/chopratejas/headroom/blob/main/pyproject.toml) and Maturin
- **uv** is the officially supported tool for dependency management and toolchain installation
- Install with `uv pip install -e ".[dev,relevance,proxy]"` to enable all development features
- Always run `uv run pytest` and `uv run ruff check` before committing changes
- The [`.devcontainer/devcontainer.json`](https://github.com/chopratejas/headroom/blob/main/.devcontainer/devcontainer.json) provides a turnkey Docker-based alternative with Node, Rust, and Python pre-configured

## Frequently Asked Questions

### Do I need to install Rust manually to set up a development environment for Headroom?

No. When you use `uv sync --extra dev`, the dependency resolver automatically handles the Rust toolchain required to build the `headroom-core` crate. The devcontainer also comes with Rust 1.95 pre-installed, so manual Rust installation is only necessary if you bypass both `uv` and the container setup.

### What is the difference between `uv sync` and `uv pip install` in the Headroom workflow?

`uv sync --extra dev` aligns your environment with the lockfile and installs the Rust toolchain alongside Python packages. `uv pip install -e ".[dev,relevance,proxy]"` then installs the Headroom package itself in editable mode with specific optional extras enabled. You need both steps: the first prepares the environment, while the second makes the local `headroom` package importable.

### Why does the devcontainer forward port 8787 specifically?

Port 8787 is the default port for the Headroom proxy server. The [`.devcontainer/devcontainer.json`](https://github.com/chopratejas/headroom/blob/main/.devcontainer/devcontainer.json) configuration forwards this port so developers can run `headroom proxy --port 8787` inside the container and still access it from their host machine's browser or CLI tools at `localhost:8787`.

### Can I use pip instead of uv to set up the development environment?

While possible, it is not recommended. The [`CONTRIBUTING.md`](https://github.com/chopratejas/headroom/blob/main/CONTRIBUTING.md) and CI workflows assume `uv` usage, which handles the Rust build dependencies more reliably than standard pip. If you must use pip, you will need to manually install the Rust toolchain and build the core crate before installing Python dependencies.