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

Supported providers

• 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.

F