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

• 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

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

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.