headroomhq 0.1.7 → 0.1.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +25 -25
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
<div align="center">
|
|
2
2
|
|
|
3
|
-
<img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.
|
|
3
|
+
<img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.9/apps/web/public/favicon.svg?sanitize=true" width="72" height="72" alt="Headroom logo">
|
|
4
4
|
|
|
5
5
|
# Headroom
|
|
6
6
|
|
|
@@ -10,19 +10,19 @@ Self-hosted dashboard for Claude, Codex, Cursor, Copilot, Grok, Antigravity and
|
|
|
10
10
|
Live limits, resets, credits and spend for every account, with credentials encrypted on your own server.
|
|
11
11
|
|
|
12
12
|
[](https://github.com/amitray007/headroom/actions/workflows/ci.yml)
|
|
13
|
-
[](https://github.com/amitray007/headroom/blob/v0.1.
|
|
13
|
+
[](https://github.com/amitray007/headroom/blob/v0.1.9/LICENSE)
|
|
14
14
|
[](#quick-start)
|
|
15
15
|
[](https://bun.sh)
|
|
16
|
-
[](https://github.com/amitray007/headroom/blob/v0.1.
|
|
17
|
-
[](https://github.com/amitray007/headroom/blob/v0.1.
|
|
18
|
-
[](https://github.com/amitray007/headroom/blob/v0.1.
|
|
16
|
+
[](https://github.com/amitray007/headroom/blob/v0.1.9/tsconfig.json)
|
|
17
|
+
[](https://github.com/amitray007/headroom/blob/v0.1.9/apps/web)
|
|
18
|
+
[](https://github.com/amitray007/headroom/blob/v0.1.9/docs/architecture/data-model.md)
|
|
19
19
|
[](#docker)
|
|
20
|
-
[](https://github.com/amitray007/headroom/blob/v0.1.
|
|
20
|
+
[](https://github.com/amitray007/headroom/blob/v0.1.9/CONTRIBUTING.md)
|
|
21
21
|
[](https://github.com/sponsors/amitray007)
|
|
22
22
|
|
|
23
|
-
[Live demo](https://headroom.theblank.club/) · [Quick start](#quick-start) · [Screenshots](#screenshots) · [Providers](#supported-providers) · [How it works](#how-it-works) · [Docs](https://github.com/amitray007/headroom/blob/v0.1.
|
|
23
|
+
[Live demo](https://headroom.theblank.club/) · [Quick start](#quick-start) · [Screenshots](#screenshots) · [Providers](#supported-providers) · [How it works](#how-it-works) · [Docs](https://github.com/amitray007/headroom/blob/v0.1.9/docs/README.md)
|
|
24
24
|
|
|
25
|
-
<img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.
|
|
25
|
+
<img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.9/media/exports/readme/headroom-loop.gif" alt="Headroom tour: one panel per account, accounts sorted by how close they are to their limit, the account to use next, reset times on a timeline, and spend in one currency" width="900">
|
|
26
26
|
|
|
27
27
|
<sub>All screenshots use Demo Mode: synthetic accounts on reserved <code>example</code> domains.</sub>
|
|
28
28
|
|
|
@@ -45,7 +45,7 @@ Headroom holds the sign-in tokens for every AI account you connect. A hosted cop
|
|
|
45
45
|
- **See resets coming.** Timeline lays every window on a calendar, so you know when headroom comes back.
|
|
46
46
|
- **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.
|
|
47
47
|
- **Track what you pay.** Wallet totals subscriptions, usage spend and top-ups in one currency, with upcoming renewals.
|
|
48
|
-
- **Get warned in time.** In-app notices, Telegram and signed webhooks for limits running low, new and expiring resets, early resets, your own spend budgets and broken sign-ins.
|
|
48
|
+
- **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.
|
|
49
49
|
- **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.
|
|
50
50
|
- **Many accounts per provider.** Personal, work and side-project accounts stay separate, each with its own credentials.
|
|
51
51
|
- **Private by design.** One owner, passkeys, encrypted credentials, and a Privacy Mode that blurs emails on screen.
|
|
@@ -55,18 +55,18 @@ Headroom holds the sign-in tokens for every AI account you connect. A hosted cop
|
|
|
55
55
|
|
|
56
56
|
| Overview | Compare |
|
|
57
57
|
| :---: | :---: |
|
|
58
|
-
| <img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.
|
|
58
|
+
| <img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.9/docs/assets/screenshots/overview.png" alt="Overview: one panel per account with its limits, credits and resets" width="420"> | <img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.9/docs/assets/screenshots/compare.png" alt="Compare: accounts of one provider ranked by room left, with a recommendation" width="420"> |
|
|
59
59
|
| **Timeline** | **Wallet** |
|
|
60
|
-
| <img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.
|
|
60
|
+
| <img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.9/docs/assets/screenshots/timeline.png" alt="Timeline: limit windows on a two-week calendar" width="420"> | <img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.9/docs/assets/screenshots/wallet.png" alt="Wallet: monthly spend by provider, top-ups and renewals" width="420"> |
|
|
61
61
|
| **Analytics** | **Detailed** |
|
|
62
|
-
| <img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.
|
|
62
|
+
| <img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.9/docs/assets/screenshots/analytics.png" alt="Analytics: when each account is busy, hour by hour, and which plans fit" width="420"> | <img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.9/docs/assets/screenshots/detailed.png" alt="Detailed: every account in one list, closest to its limit first" width="420"> |
|
|
63
63
|
| **Connect** | **Light theme** |
|
|
64
|
-
| <img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.
|
|
64
|
+
| <img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.9/docs/assets/screenshots/connect.png" alt="Connect: pick a provider and manage connected accounts" width="420"> | <img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.9/docs/assets/screenshots/overview-light.png" alt="Overview in the light theme" width="420"> |
|
|
65
65
|
|
|
66
66
|
<p align="center">
|
|
67
|
-
<img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.
|
|
67
|
+
<img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.9/docs/assets/screenshots/mobile-detailed.png" alt="Detailed view on a phone" width="240">
|
|
68
68
|
|
|
69
|
-
<img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.
|
|
69
|
+
<img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.9/docs/assets/screenshots/mobile-wallet.png" alt="Wallet on a phone" width="240">
|
|
70
70
|
</p>
|
|
71
71
|
|
|
72
72
|
## Supported providers
|
|
@@ -84,7 +84,7 @@ Headroom holds the sign-in tokens for every AI account you connect. A hosted cop
|
|
|
84
84
|
- **Private:** the endpoint the provider's own app or CLI calls. It can change without notice.
|
|
85
85
|
- **Official:** a published API.
|
|
86
86
|
- **Enable providers** with `HEADROOM_ENABLED_PROVIDERS`. The default is all seven.
|
|
87
|
-
- **Evidence:** the [provider dossiers](https://github.com/amitray007/headroom/blob/v0.1.
|
|
87
|
+
- **Evidence:** the [provider dossiers](https://github.com/amitray007/headroom/blob/v0.1.9/docs/providers/README.md) record what is validated.
|
|
88
88
|
|
|
89
89
|
## How it works
|
|
90
90
|
|
|
@@ -108,9 +108,9 @@ flowchart LR
|
|
|
108
108
|
## Quick start
|
|
109
109
|
|
|
110
110
|
> [!WARNING]
|
|
111
|
-
> 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](https://github.com/amitray007/headroom/blob/v0.1.
|
|
111
|
+
> 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](https://github.com/amitray007/headroom/blob/v0.1.9/DISCLAIMER.md) first.
|
|
112
112
|
|
|
113
|
-
Every way to install, update and remove Headroom is in [Install](https://github.com/amitray007/headroom/blob/v0.1.
|
|
113
|
+
Every way to install, update and remove Headroom is in [Install](https://github.com/amitray007/headroom/blob/v0.1.9/docs/operations/install.md).
|
|
114
114
|
|
|
115
115
|
### Installer
|
|
116
116
|
|
|
@@ -144,7 +144,7 @@ docker run -d --name headroom -p 8080:8080 \
|
|
|
144
144
|
ghcr.io/amitray007/headroom:latest
|
|
145
145
|
```
|
|
146
146
|
|
|
147
|
-
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](https://github.com/amitray007/headroom/blob/v0.1.
|
|
147
|
+
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](https://github.com/amitray007/headroom/blob/v0.1.9/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](https://github.com/amitray007/headroom/blob/v0.1.9/docs/operations/releases.md).
|
|
148
148
|
|
|
149
149
|
### Docker on a Tailscale tailnet
|
|
150
150
|
|
|
@@ -156,7 +156,7 @@ cp .env.example .env # set TS_AUTHKEY and HEADROOM_PUBLIC_URL
|
|
|
156
156
|
docker compose up -d --build
|
|
157
157
|
```
|
|
158
158
|
|
|
159
|
-
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](https://github.com/amitray007/headroom/blob/v0.1.
|
|
159
|
+
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](https://github.com/amitray007/headroom/blob/v0.1.9/docs/operations/tailscale.md).
|
|
160
160
|
|
|
161
161
|
### From source
|
|
162
162
|
|
|
@@ -171,7 +171,7 @@ Open <http://localhost:8080>. In the checkout, `mise` sets data to `.data/` and
|
|
|
171
171
|
|
|
172
172
|
### The binary
|
|
173
173
|
|
|
174
|
-
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](https://github.com/amitray007/headroom/blob/v0.1.
|
|
174
|
+
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](https://github.com/amitray007/headroom/blob/v0.1.9/docs/operations/install.md).
|
|
175
175
|
|
|
176
176
|
```sh
|
|
177
177
|
headroom --open # serve on 127.0.0.1:8080 and open the dashboard
|
|
@@ -198,7 +198,7 @@ headroom service uninstall
|
|
|
198
198
|
| `HEADROOM_AUTH_SECRET_FILE` | same folder as the key, `headroom.auth-secret` | Session signing secret |
|
|
199
199
|
| `HEADROOM_CODEX_BIN`, `HEADROOM_CLAUDE_BIN`, `HEADROOM_GROK_BIN` | resolved on `PATH` | Absolute path of a sign-in CLI |
|
|
200
200
|
|
|
201
|
-
Every variable is listed in [Deployment and credential storage](https://github.com/amitray007/headroom/blob/v0.1.
|
|
201
|
+
Every variable is listed in [Deployment and credential storage](https://github.com/amitray007/headroom/blob/v0.1.9/docs/architecture/deployment.md).
|
|
202
202
|
|
|
203
203
|
## Security
|
|
204
204
|
|
|
@@ -208,7 +208,7 @@ Every variable is listed in [Deployment and credential storage](https://github.c
|
|
|
208
208
|
- Provider errors are mapped to fixed messages, so raw responses never reach logs or the browser.
|
|
209
209
|
- Demo Mode swaps in synthetic data for screenshots, and Privacy Mode blurs identities on screen.
|
|
210
210
|
|
|
211
|
-
Report a vulnerability privately as described in [SECURITY.md](https://github.com/amitray007/headroom/blob/v0.1.
|
|
211
|
+
Report a vulnerability privately as described in [SECURITY.md](https://github.com/amitray007/headroom/blob/v0.1.9/SECURITY.md).
|
|
212
212
|
|
|
213
213
|
## Development
|
|
214
214
|
|
|
@@ -227,7 +227,7 @@ packages/connectors/* One direct-HTTP client per provider
|
|
|
227
227
|
docs/ Product, architecture, provider research, decisions
|
|
228
228
|
```
|
|
229
229
|
|
|
230
|
-
Start with [CONTRIBUTING.md](https://github.com/amitray007/headroom/blob/v0.1.
|
|
230
|
+
Start with [CONTRIBUTING.md](https://github.com/amitray007/headroom/blob/v0.1.9/CONTRIBUTING.md) and the [documentation index](https://github.com/amitray007/headroom/blob/v0.1.9/docs/README.md).
|
|
231
231
|
|
|
232
232
|
## Support
|
|
233
233
|
|
|
@@ -235,7 +235,7 @@ Headroom is free, and there is no paid cloud version. If it saves you a surprise
|
|
|
235
235
|
|
|
236
236
|
## License
|
|
237
237
|
|
|
238
|
-
[MIT](https://github.com/amitray007/headroom/blob/v0.1.
|
|
238
|
+
[MIT](https://github.com/amitray007/headroom/blob/v0.1.9/LICENSE). Headroom also contains work from other projects under their own licenses: see [Third-party notices](https://github.com/amitray007/headroom/blob/v0.1.9/THIRD_PARTY_NOTICES.md) and [LICENSES/](https://github.com/amitray007/headroom/blob/v0.1.9/LICENSES/README.md). See also the [Disclaimer](https://github.com/amitray007/headroom/blob/v0.1.9/DISCLAIMER.md).
|
|
239
239
|
|
|
240
240
|
> [!NOTE]
|
|
241
241
|
> Headroom is an independent project, not affiliated with any provider listed above. Product names are trademarks of their owners.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "headroomhq",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.9",
|
|
4
4
|
"bugs": "https://github.com/amitray007/headroom/issues",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -18,10 +18,10 @@
|
|
|
18
18
|
"THIRD_PARTY_NOTICES.md"
|
|
19
19
|
],
|
|
20
20
|
"optionalDependencies": {
|
|
21
|
-
"headroomhq-darwin-arm64": "0.1.
|
|
22
|
-
"headroomhq-darwin-x64": "0.1.
|
|
23
|
-
"headroomhq-linux-x64": "0.1.
|
|
24
|
-
"headroomhq-linux-arm64": "0.1.
|
|
21
|
+
"headroomhq-darwin-arm64": "0.1.9",
|
|
22
|
+
"headroomhq-darwin-x64": "0.1.9",
|
|
23
|
+
"headroomhq-linux-x64": "0.1.9",
|
|
24
|
+
"headroomhq-linux-arm64": "0.1.9"
|
|
25
25
|
},
|
|
26
26
|
"engines": {
|
|
27
27
|
"node": ">=18"
|