Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

docs(install): document Windows build prerequisites

RTCartist794916bf1a66
diff --git a/docs/content/docs/installation.mdx b/docs/content/docs/installation.mdx
index acd9ce878..b86da4f51 100644
--- a/docs/content/docs/installation.mdx
+++ b/docs/content/docs/installation.mdx
@@ -6,8 +6,11 @@ description: Install Headroom via pip, npm, or Docker. Includes all Python extra
## Python
Headroom requires **Python 3.10+** and is published as `headroom-ai` on PyPI.
-Current release wheels are built for Python **3.10 through 3.13**. If your
-installer is using a newer Python, force a supported interpreter.
+Current release wheels are built for Python **3.10 through 3.13** on Linux
+(manylinux_2_28 x86_64 / aarch64) and macOS (Apple Silicon). Other targets —
+**Windows** and **Intel macOS** — fall back to building the Rust extension
+from the sdist and need a working native toolchain. If your installer is
+using a newer Python, force a supported interpreter.
### Core package
@@ -48,6 +51,40 @@ You can combine extras:
pip install "headroom-ai[proxy,langchain,ml]"
```
+### Windows
+
+There are no prebuilt Windows wheels yet, so `pip install headroom-ai`
+(and `uv tool install`, `pipx install`, …) will fall back to building the
+Rust extension from the sdist. The build needs the MSVC toolchain on
+`PATH`. Without it you'll see:
+
+```text
+error: linker `link.exe` not found
+note: please ensure that Visual Studio 2017 or later, or Build Tools for
+Visual Studio were installed with the Visual C++ option
+```
+
+To install the prerequisites:
+
+1. **MSVC toolchain** — install **[Build Tools for Visual Studio](https://visualstudio.microsoft.com/visual-cpp-build-tools/)**
+ and select the *"Desktop development with C++"* workload (this gives
+ you `link.exe`). VS Code on its own is not enough.
+2. **Rust** — install via [rustup](https://rustup.rs/). Choose the
+ `stable-x86_64-pc-windows-msvc` toolchain so Cargo uses the MSVC
+ linker you just installed.
+3. **Open a fresh PowerShell** so the installer's PATH updates take
+ effect, then run the install:
+
+ ```powershell
+ uv tool install --python 3.13 "headroom-ai[all]"
+ # or
+ pip install "headroom-ai[all]"
+ ```
+
+If you'd rather avoid the native toolchain entirely, run Headroom
+through Docker — see the [Docker](#docker) section below. Native
+Windows wheels are tracked in [#636](https://github.com/chopratejas/headroom/issues/636).
+
### pipx
`pipx` creates one virtual environment per app. If that environment uses an