headroomhq 0.1.6 → 0.1.7
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 +26 -23
- 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.7/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.7/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.7/tsconfig.json)
|
|
17
|
+
[](https://github.com/amitray007/headroom/blob/v0.1.7/apps/web)
|
|
18
|
+
[](https://github.com/amitray007/headroom/blob/v0.1.7/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.7/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.7/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.7/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
|
|
|
@@ -43,6 +43,7 @@ Headroom holds the sign-in tokens for every AI account you connect. A hosted cop
|
|
|
43
43
|
- **Every limit in one place.** 5-hour sessions, weekly pools, per-model limits, credit balances, banked resets and on-demand spend, side by side.
|
|
44
44
|
- **Know which account to use next.** Compare ranks accounts of a provider by the room they have left and names the one to use.
|
|
45
45
|
- **See resets coming.** Timeline lays every window on a calendar, so you know when headroom comes back.
|
|
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.
|
|
46
47
|
- **Track what you pay.** Wallet totals subscriptions, usage spend and top-ups in one currency, with upcoming renewals.
|
|
47
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
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.
|
|
@@ -54,16 +55,18 @@ Headroom holds the sign-in tokens for every AI account you connect. A hosted cop
|
|
|
54
55
|
|
|
55
56
|
| Overview | Compare |
|
|
56
57
|
| :---: | :---: |
|
|
57
|
-
| <img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.
|
|
58
|
+
| <img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.7/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.7/docs/assets/screenshots/compare.png" alt="Compare: accounts of one provider ranked by room left, with a recommendation" width="420"> |
|
|
58
59
|
| **Timeline** | **Wallet** |
|
|
59
|
-
| <img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.
|
|
60
|
+
| <img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.7/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.7/docs/assets/screenshots/wallet.png" alt="Wallet: monthly spend by provider, top-ups and renewals" width="420"> |
|
|
61
|
+
| **Analytics** | **Detailed** |
|
|
62
|
+
| <img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.7/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.7/docs/assets/screenshots/detailed.png" alt="Detailed: every account in one list, closest to its limit first" width="420"> |
|
|
60
63
|
| **Connect** | **Light theme** |
|
|
61
|
-
| <img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.
|
|
64
|
+
| <img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.7/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.7/docs/assets/screenshots/overview-light.png" alt="Overview in the light theme" width="420"> |
|
|
62
65
|
|
|
63
66
|
<p align="center">
|
|
64
|
-
<img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.
|
|
67
|
+
<img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.7/docs/assets/screenshots/mobile-detailed.png" alt="Detailed view on a phone" width="240">
|
|
65
68
|
|
|
66
|
-
<img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.
|
|
69
|
+
<img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.7/docs/assets/screenshots/mobile-wallet.png" alt="Wallet on a phone" width="240">
|
|
67
70
|
</p>
|
|
68
71
|
|
|
69
72
|
## Supported providers
|
|
@@ -81,7 +84,7 @@ Headroom holds the sign-in tokens for every AI account you connect. A hosted cop
|
|
|
81
84
|
- **Private:** the endpoint the provider's own app or CLI calls. It can change without notice.
|
|
82
85
|
- **Official:** a published API.
|
|
83
86
|
- **Enable providers** with `HEADROOM_ENABLED_PROVIDERS`. The default is all seven.
|
|
84
|
-
- **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.7/docs/providers/README.md) record what is validated.
|
|
85
88
|
|
|
86
89
|
## How it works
|
|
87
90
|
|
|
@@ -105,9 +108,9 @@ flowchart LR
|
|
|
105
108
|
## Quick start
|
|
106
109
|
|
|
107
110
|
> [!WARNING]
|
|
108
|
-
> 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.7/DISCLAIMER.md) first.
|
|
109
112
|
|
|
110
|
-
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.7/docs/operations/install.md).
|
|
111
114
|
|
|
112
115
|
### Installer
|
|
113
116
|
|
|
@@ -141,7 +144,7 @@ docker run -d --name headroom -p 8080:8080 \
|
|
|
141
144
|
ghcr.io/amitray007/headroom:latest
|
|
142
145
|
```
|
|
143
146
|
|
|
144
|
-
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.7/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.7/docs/operations/releases.md).
|
|
145
148
|
|
|
146
149
|
### Docker on a Tailscale tailnet
|
|
147
150
|
|
|
@@ -153,7 +156,7 @@ cp .env.example .env # set TS_AUTHKEY and HEADROOM_PUBLIC_URL
|
|
|
153
156
|
docker compose up -d --build
|
|
154
157
|
```
|
|
155
158
|
|
|
156
|
-
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.7/docs/operations/tailscale.md).
|
|
157
160
|
|
|
158
161
|
### From source
|
|
159
162
|
|
|
@@ -168,7 +171,7 @@ Open <http://localhost:8080>. In the checkout, `mise` sets data to `.data/` and
|
|
|
168
171
|
|
|
169
172
|
### The binary
|
|
170
173
|
|
|
171
|
-
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.7/docs/operations/install.md).
|
|
172
175
|
|
|
173
176
|
```sh
|
|
174
177
|
headroom --open # serve on 127.0.0.1:8080 and open the dashboard
|
|
@@ -195,7 +198,7 @@ headroom service uninstall
|
|
|
195
198
|
| `HEADROOM_AUTH_SECRET_FILE` | same folder as the key, `headroom.auth-secret` | Session signing secret |
|
|
196
199
|
| `HEADROOM_CODEX_BIN`, `HEADROOM_CLAUDE_BIN`, `HEADROOM_GROK_BIN` | resolved on `PATH` | Absolute path of a sign-in CLI |
|
|
197
200
|
|
|
198
|
-
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.7/docs/architecture/deployment.md).
|
|
199
202
|
|
|
200
203
|
## Security
|
|
201
204
|
|
|
@@ -205,7 +208,7 @@ Every variable is listed in [Deployment and credential storage](https://github.c
|
|
|
205
208
|
- Provider errors are mapped to fixed messages, so raw responses never reach logs or the browser.
|
|
206
209
|
- Demo Mode swaps in synthetic data for screenshots, and Privacy Mode blurs identities on screen.
|
|
207
210
|
|
|
208
|
-
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.7/SECURITY.md).
|
|
209
212
|
|
|
210
213
|
## Development
|
|
211
214
|
|
|
@@ -224,7 +227,7 @@ packages/connectors/* One direct-HTTP client per provider
|
|
|
224
227
|
docs/ Product, architecture, provider research, decisions
|
|
225
228
|
```
|
|
226
229
|
|
|
227
|
-
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.7/CONTRIBUTING.md) and the [documentation index](https://github.com/amitray007/headroom/blob/v0.1.7/docs/README.md).
|
|
228
231
|
|
|
229
232
|
## Support
|
|
230
233
|
|
|
@@ -232,7 +235,7 @@ Headroom is free, and there is no paid cloud version. If it saves you a surprise
|
|
|
232
235
|
|
|
233
236
|
## License
|
|
234
237
|
|
|
235
|
-
[MIT](https://github.com/amitray007/headroom/blob/v0.1.
|
|
238
|
+
[MIT](https://github.com/amitray007/headroom/blob/v0.1.7/LICENSE). Headroom also contains work from other projects under their own licenses: see [Third-party notices](https://github.com/amitray007/headroom/blob/v0.1.7/THIRD_PARTY_NOTICES.md) and [LICENSES/](https://github.com/amitray007/headroom/blob/v0.1.7/LICENSES/README.md). See also the [Disclaimer](https://github.com/amitray007/headroom/blob/v0.1.7/DISCLAIMER.md).
|
|
236
239
|
|
|
237
240
|
> [!NOTE]
|
|
238
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.7",
|
|
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.7",
|
|
22
|
+
"headroomhq-darwin-x64": "0.1.7",
|
|
23
|
+
"headroomhq-linux-x64": "0.1.7",
|
|
24
|
+
"headroomhq-linux-arm64": "0.1.7"
|
|
25
25
|
},
|
|
26
26
|
"engines": {
|
|
27
27
|
"node": ">=18"
|