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

docs(install): document corporate SSL-inspection workaround (#735) (#775)

Browse source 
Fixes #735.

Adds a README **Install → Corporate / SSL-inspection environments**
subsection.

Behind a corporate MITM / SSL-inspection proxy, `pip install
"headroom-ai[all]"` fails with
`CERTIFICATE_VERIFY_FAILED` because the build downloads `rustup` (via
maturin) and the runtime
assets over a connection the local TLS stack doesn't trust. The new
section documents:

- Installing Rust first (so maturin doesn't fetch `rustup`), and
preferring a prebuilt wheel.
- Trusting the corporate CA (`REQUESTS_CA_BUNDLE` / `SSL_CERT_FILE` /
`CURL_CA_BUNDLE`) for the
two TLS-fetched runtime assets: `cdn.pyke.io` (ONNX Runtime;
`ORT_STRATEGY=system` fallback)
  and `huggingface.co` (kompress-base model; `HF_HUB_OFFLINE` fallback).

Docs only; no code paths changed.
This commit is contained in:
Khalid Shaikh 2026-06-11 21:31:52 +05:30 • committed by GitHub
parent 34dafe69d9
commit 650b776dd5
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 27 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

27
README.md
View file

@ -238,6 +238,33 @@ pipx install --python python3.13 "headroom-ai[all]"
→ [Installation guide](https://headroom-docs.vercel.app/docs/installation) — Docker tags, persistent service, PowerShell, devcontainers.
### Corporate / SSL-inspection environments
If `pip install "headroom-ai[all]"` fails with `CERTIFICATE_VERIFY_FAILED`
(`unable to get local issuer certificate`), your network uses **SSL inspection** — a MITM
proxy presenting a company-issued CA. The build backend (`maturin`) downloads `rustup` over a
connection your TLS stack doesn't trust. **Install Rust first** so the build doesn't fetch it:
```bash
# macOS / Linux
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh && rustup default stable
# Windows
winget install Rustlang.Rustup && rustup default stable
```
Restart your shell, then `pip install "headroom-ai[all]"`. A prebuilt wheel avoids the Rust
build entirely where available: `pip install --only-binary headroom-ai headroom-ai`.
Two runtime assets are fetched over TLS; if they are blocked, trust your corporate CA via
`REQUESTS_CA_BUNDLE` / `SSL_CERT_FILE` / `CURL_CA_BUNDLE`:
- **`cdn.pyke.io`** — the ONNX Runtime for the Rust core. Alternatively pre-provide it with
`ORT_STRATEGY=system` and `ORT_LIB_LOCATION=/path/to/onnxruntime`.
- **`huggingface.co`** — the `kompress-base` compression model. Pre-download it and run with
`HF_HUB_OFFLINE=1`, or set `HF_ENDPOINT` to a trusted mirror.
Running with compression disabled (pure gateway) requires neither asset.
## headroom learn
<p align="center">