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.

fix(docs): fix Docker example and document hnswlib C++ build requirement

Long Ngo693deb4d58a4
diff --git a/docs/proxy.md b/docs/proxy.md
index 752462868..2dc58091b 100644
--- a/docs/proxy.md
+++ b/docs/proxy.md
@@ -248,7 +248,12 @@ Or with Docker:
```dockerfile
FROM python:3.11-slim
-RUN pip install headroom[proxy]
+RUN apt-get update && apt-get install -y --no-install-recommends build-essential \
+ && pip install "headroom-ai[proxy]" \
+ && apt-get purge -y build-essential && apt-get autoremove -y \
+ && rm -rf /var/lib/apt/lists/*
EXPOSE 8787
CMD ["headroom", "proxy", "--host", "0.0.0.0"]
```
+
+> **Note:** `build-essential` is required at install time because `headroom-ai` includes `hnswlib`, a C++ extension that must be compiled from source. It is removed after installation to keep the image slim.
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 1524a87b5..e2af281c4 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -219,6 +219,39 @@ client = HeadroomClient(
## Import/Installation Issues
+### "pip install fails with C++ compilation error"
+
+**Symptom**: Installation fails with an error like:
+
+```
+RuntimeError: Unsupported compiler -- at least C++11 support is needed!
+ERROR: Failed building wheel for hnswlib
+```
+
+**Cause**: `headroom-ai` depends on `hnswlib`, a C++ extension that must be compiled from source. Slim environments (Docker slim images, minimal CI runners) lack the required build tools.
+
+**Solutions**:
+
+```bash
+# Linux / Debian-based (including Docker)
+apt-get install -y build-essential && pip install headroom-ai
+
+# macOS (Xcode command line tools)
+xcode-select --install && pip install headroom-ai
+```
+
+In a Dockerfile, install and remove build tools in one layer to keep the image slim:
+
+```dockerfile
+FROM python:3.11-slim
+RUN apt-get update && apt-get install -y --no-install-recommends build-essential \
+ && pip install "headroom-ai[proxy]" \
+ && apt-get purge -y build-essential && apt-get autoremove -y \
+ && rm -rf /var/lib/apt/lists/*
+```
+
+---
+
### "ModuleNotFoundError: No module named 'headroom'"
```bash