Headroom
Every AI plan you pay for, on one screen.
Self-hosted dashboard for Claude, Codex, Cursor, Copilot, Grok, Antigravity and Vercel AI Gateway.
Live limits, resets, credits and spend for every account, with credentials encrypted on your own server.
Live demo · Quick start · Screenshots · Providers · How it works · Docs
All screenshots use Demo Mode: synthetic accounts on reserved example domains.
Why Headroom
You pay for several AI plans, often more than one account each. Each one shows its limits somewhere else, in a different unit, with a different reset. You find out an account is spent when a request fails halfway through a task.
Headroom signs in to each account once, refreshes them in the background, and shows everything on one page: what is left, when it resets, which account to use next, and what it all costs.
Why there is no cloud version
Headroom holds the sign-in tokens for every AI account you connect. A hosted copy would put everyone's tokens on one server that someone else runs, which defeats the purpose. Run it on a server you control, and your tokens stay there. There is no hosted Headroom, and none is planned.
Features
- Every limit in one place. 5-hour sessions, weekly pools, per-model limits, credit balances, banked resets and on-demand spend, side by side.
- Know which account to use next. Compare ranks accounts of a provider by the room they have left and names the one to use.
- See resets coming. Timeline lays every window on a calendar, so you know when headroom comes back.
- See how you use your limits. Analytics shows when you work, when you run out, and whether each plan fits, from the readings Headroom stores.
- Track what you pay. Wallet totals subscriptions, usage spend and top-ups in one currency, with upcoming renewals.
- Get warned in time. In-app notices, Telegram and signed webhooks for limits running low or on pace to run out before they reset, new and expiring resets, early resets, your own spend budgets and broken sign-ins.
- Automations you switch on. Use a banked Codex reset when a limit runs out, and record credit top-ups in the Wallet as soon as a balance rises.
- Many accounts per provider. Personal, work and side-project accounts stay separate, each with its own credentials.
- Private by design. One owner, passkeys, encrypted credentials, and a Privacy Mode that blurs emails on screen.
- Works on your phone. Every view is built for small screens.
Screenshots
| Overview | Compare |
|---|
| |
| Timeline | Wallet |
| |
| Analytics | Detailed |
| |
| Connect | Light theme |
| |
Supported providers
| Provider | Sign-in | What you see | Interface |
|---|
| Claude | Claude Code sign-in, or import .credentials.json | Session and weekly limits, per-model limits, extra-usage spend, reset grants | Private |
| Codex | Codex CLI device sign-in, or import auth.json | 5-hour and weekly limits, credits, banked reset credits | Private |
| Cursor | Browser approval | Included usage, Auto and API pools, Grok Bot, on-demand spend | Private |
| Copilot | GitHub device code, or import a gh token | AI credits, credits used, extra usage, chat and completions | Private |
| Grok | Grok CLI device sign-in, or import auth.json | Weekly pool, chat and code share, on-demand cap, prepaid balance | Private |
| Antigravity | Google sign-in, then paste the redirect | Gemini and Claude/GPT quota pools | Private |
| Vercel AI Gateway | API key | Credit balance, credits used, spend | Official |
- Private: the endpoint the provider's own app or CLI calls. It can change without notice.
- Official: a published API.
- Enable providers with
HEADROOM_ENABLED_PROVIDERS. The default is all seven.
- Evidence: the provider dossiers record what is validated.
How it works
flowchart LR
you([You]) -->|browser or phone| web[Web app]
web -->|session-checked API| server[Headroom server]
server --> db[(SQLite<br/>credentials sealed<br/>with AES-256-GCM)]
server --> sched[Scheduler]
sched --> conn[Connectors]
conn -->|direct HTTPS| prov[Provider APIs]
cli[Official CLI] -.->|once, at sign-in| server
server -->|alerts| out[Telegram / webhooks]
- Sign in once. Where a provider needs it, its official CLI runs one time on the server to sign in. Headroom seals the result with a master key kept outside the database.
- Refresh in the background. The scheduler collects each account over direct HTTPS on your interval, refreshes tokens before they expire, and keeps 90 days of history by default.
- Read only by default. Monitoring never sends a model request, redeems a reset or buys credits. Using a banked Codex reset needs "Allow Account Actions" and either a press-and-hold or an auto-reset rule you set.
- Unknown is not zero. A figure a provider does not report shows as unknown, never as 0.
Quick start
[!WARNING]
Headroom reads private provider endpoints. A provider can restrict, suspend or ban an account for this kind of access. Use it at your own risk: the authors are not responsible for what happens to your accounts. Read the Disclaimer first.
Every way to install, update and remove Headroom is in Install.
Installer
curl -fsSL https://headroom.theblank.club/install | sh
headroom --open # serve on 127.0.0.1:8080 and open the dashboard
headroom service install # start at login
The script checks the download against the release checksums and puts headroom in ~/.local/bin. Run it again, or run headroom update, to upgrade. It supports macOS and Linux on arm64 and x64.
Homebrew
brew tap amitray007/headroom https://github.com/amitray007/headroom
brew install amitray007/headroom/headroom
brew services start headroom
Package runners
npx headroomhq # or bunx headroomhq, uvx headroomhq, pipx run headroomhq
Docker
docker run -d --name headroom -p 8080:8080 \
-v headroom-data:/var/lib/headroom/data -v headroom-secrets:/etc/headroom \
ghcr.io/amitray007/headroom:latest
Open http://localhost:8080 and create the owner account. Back up both volumes together: without the key, every account must be reconnected. A compose file is deploy/compose.simple.yaml. To reach Headroom from other devices, put an HTTPS reverse proxy in front and set HEADROOM_PUBLIC_URL to its address. Image tags are in Releases.
Docker on a Tailscale tailnet
Headroom publishes no port. A Tailscale container serves it over HTTPS to your own devices only.
git clone https://github.com/amitray007/headroom.git && cd headroom/deploy
cp .env.example .env # set TS_AUTHKEY and HEADROOM_PUBLIC_URL
docker compose up -d --build
Open https://<TS_HOSTNAME>.<tailnet>.ts.net and create the owner account. The full guide, including Dokploy and moving an existing instance, is in Self-hosting on a tailnet.
From source
Requires mise, which installs the pinned Bun.
mise install && mise run install
mise run start # builds the web app and the binary, then serves on :8080
Open http://localhost:8080. In the checkout, mise sets data to .data/ and the two secret files to .state/. Back up .state/headroom.key with .data/headroom.db: without the key every account must be reconnected.
The binary
The binary keeps per-user state: on macOS under ~/Library/Application Support/Headroom/, on Linux data in ${XDG_DATA_HOME:-~/.local/share}/headroom/ and the key and secret in ${XDG_CONFIG_HOME:-~/.config}/headroom/. Codex, Claude and Grok sign in through their official CLI: install it on the same machine, or use Import. See Install.
headroom --open # serve on 127.0.0.1:8080 and open the dashboard
headroom --help # commands, flags and the resolved file locations
headroom paths # print the data, key and secret locations
headroom update # install the newest release (--check only reports)
headroom service install # run at login (launchd on macOS, a systemd user unit on Linux)
headroom service status # installed and running?
headroom service uninstall
service install must run from the compiled binary, not bun. On a headless Linux server also run loginctl enable-linger $USER. Back up the key with the database.
Configuration
| Variable | Default | Purpose |
|---|
HEADROOM_PUBLIC_URL | none | The address you open Headroom at. Required behind a proxy; passkeys and cookies use it |
HEADROOM_ENABLED_PROVIDERS | all seven | Comma list: codex, claude, grok, antigravity, copilot, cursor, vercel_ai_gateway |
HEADROOM_HOST | 127.0.0.1 | Listen address. The container image sets 0.0.0.0 |
HEADROOM_PORT | 8080 | HTTP port (--port overrides) |
HEADROOM_DATA_DIR | macOS ~/Library/Application Support/Headroom/data, Linux ~/.local/share/headroom/data | Where the database lives |
HEADROOM_MASTER_KEY_FILE | next to the data on macOS, ~/.config/headroom/headroom.key on Linux | The key that seals credentials. Keep it out of the data folder |
HEADROOM_AUTH_SECRET_FILE | same folder as the key, headroom.auth-secret | Session signing secret |
HEADROOM_CODEX_BIN, HEADROOM_CLAUDE_BIN, HEADROOM_GROK_BIN | resolved on PATH | Absolute path of a sign-in CLI. Sign-in runs it with a private HOME, so a version-manager shim that finds the CLI through HOME fails; point this at the real binary |
Every variable is listed in Deployment and credential storage.
Security
- Credentials are sealed per account with AES-256-GCM. The master key never enters the database.
- One owner account, with username and password or passkeys. Sign-up closes after the first account.
- Provider requests time out, and a redirect to another host never carries your tokens.
- Provider errors are mapped to fixed messages, so raw responses never reach logs or the browser.
- Demo Mode swaps in synthetic data for screenshots, and Privacy Mode blurs identities on screen.
Report a vulnerability privately as described in SECURITY.md.
Development
mise run dev # API server with reload on :8080
mise exec -- bun run web:dev # Vite on :5173, proxying /api to :8080
mise run check # docs, format, lint, typecheck, knip and tests
apps/server Hono API, scheduler, notifications
apps/web React 19 app
packages/core Enumerations, stores, crypto, connector contract
packages/view-model Presenters shared by every view, Demo Mode data
packages/connectors/* One direct-HTTP client per provider
docs/ Product, architecture, provider research, decisions
Start with CONTRIBUTING.md and the documentation index.
Support
Headroom is free, and there is no paid cloud version. If it saves you a surprise limit, you can sponsor its development. Sponsorship pays for connector fixes when a provider changes its API, new providers, releases and documentation.
License
MIT. Headroom also contains work from other projects under their own licenses: see Third-party notices and LICENSES/. See also the Disclaimer.
[!NOTE]
Headroom is an independent project, not affiliated with any provider listed above. Product names are trademarks of their owners.
It is for personal self-hosted use. It reads your own accounts with your own credentials, and each provider's terms still apply. The authors and contributors are not responsible if a provider bans, suspends, blocks or restricts an account, or for any other result of using Headroom.
