akadmin/headroom
1
0
Fork 0
mirror of https://github.com/headroomlabs-ai/headroom.git synced 2026-08-27 14:17:10 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

Address PR feedback: Move troubleshooting, refine rust docs, and update install options

Browse source
This commit is contained in:
Divyanshu Singh 2026-06-07 00:27:09 +05:30
parent db69ef8257
commit 67f005e434
2 changed files with 43 additions and 59 deletions
Download patch file Download diff file Expand all files Collapse all files

60
README.md
View file

@ -280,62 +280,4 @@ Devcontainers in `.devcontainer/` (default + `memory-stack` with Qdrant & Neo4j)
## License
Apache 2.0 — see [LICENSE](LICENSE).
---
## Troubleshooting
These are common issues faced during initial setup and how to resolve them.
### Python version error
This project requires **Python 3.10+**.
Check your version:
```bash
python3 --version
```
If needed (Mac with Homebrew):
```bash
brew install python@3.11
```
---
### Editable install fails (`pip install -e`)
Upgrade pip to the latest version:
```bash
python3 -m pip install --upgrade pip
```
---
### Missing `cargo` (Rust error)
Some tests require Rust tooling.
Install Rust using the official installer:
```bash
curl https://sh.rustup.rs -sSf | sh
```
Or visit the official site:
https://rust-lang.org/tools/install/
---
### npm vs Python confusion
* This repository is primarily a **Python project**
* `npm install headroom-ai` is only for using it in JavaScript/TypeScript apps, not for development
To contribute to this repository, use:
```bash
pip install ".[dev]"
```
Apache 2.0 — see [LICENSE](LICENSE).

42
docs/content/docs/installation.mdx
View file

@ -3,6 +3,14 @@ title: Installation
description: Install Headroom via pip, npm, or Docker. Includes all Python extras, TypeScript setup, Docker image tags, and environment variables.
---
---
## Install options
**pip** - you're writing Python, or you need the CLI (`headroom proxy`, `wrap`, `mcp`, `learn`, `perf`), regardless of what language your app is in.
**npm** - you're writing TypeScript/Node and want inline `compress()`, SDK wrapping (`withHeadroom`), or Vercel AI SDK middleware.
## Python
Headroom requires **Python 3.10+** and is published as `headroom-ai` on PyPI.
@ -184,6 +192,40 @@ These variables configure Headroom at runtime. Set them in your shell, `.env` fi
| `HEADROOM_BASE_URL` | `http://localhost:8787` | Proxy URL for the TypeScript SDK |
| `HEADROOM_API_KEY` | _(none)_ | API key if the proxy requires auth |
## Troubleshooting
These are common issues faced during initial setup and how to resolve them.
### Python version error
This project requires **Python 3.10+**.
Check your version:
```bash
python3 --version
```
If needed (Mac with Homebrew):
```bash
brew install python@3.11
```
### Editable install fails (`pip install -e`)
Upgrade pip to the latest version:
```bash
python3 -m pip install --upgrade pip
```
### Missing `cargo` (Rust error)
Some tests require Rust tooling.
The recommended way to install rust is using `rustup`. You can find the official installation instructions [here](https://rust-lang.org/tools/install/).
## Next steps
<Cards>