headroomhq 0.1.3 → 0.1.5
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/LICENSE +1 -1
- package/README.md +26 -23
- package/THIRD_PARTY_NOTICES.md +2518 -0
- package/package.json +7 -6
package/LICENSE
CHANGED
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.5/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.5/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.5/tsconfig.json)
|
|
17
|
+
[](https://github.com/amitray007/headroom/blob/v0.1.5/apps/web)
|
|
18
|
+
[](https://github.com/amitray007/headroom/blob/v0.1.5/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.5/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.5/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.5/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
|
|
|
@@ -54,16 +54,16 @@ Headroom holds the sign-in tokens for every AI account you connect. A hosted cop
|
|
|
54
54
|
|
|
55
55
|
| Overview | Compare |
|
|
56
56
|
| :---: | :---: |
|
|
57
|
-
| <img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.
|
|
57
|
+
| <img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.5/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.5/docs/assets/screenshots/compare.png" alt="Compare: accounts of one provider ranked by room left, with a recommendation" width="420"> |
|
|
58
58
|
| **Timeline** | **Wallet** |
|
|
59
|
-
| <img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.
|
|
59
|
+
| <img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.5/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.5/docs/assets/screenshots/wallet.png" alt="Wallet: monthly spend by provider, top-ups and renewals" width="420"> |
|
|
60
60
|
| **Connect** | **Light theme** |
|
|
61
|
-
| <img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.
|
|
61
|
+
| <img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.5/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.5/docs/assets/screenshots/overview-light.png" alt="Overview in the light theme" width="420"> |
|
|
62
62
|
|
|
63
63
|
<p align="center">
|
|
64
|
-
<img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.
|
|
64
|
+
<img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.5/docs/assets/screenshots/mobile-detailed.png" alt="Detailed view on a phone" width="240">
|
|
65
65
|
|
|
66
|
-
<img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.
|
|
66
|
+
<img src="https://raw.githubusercontent.com/amitray007/headroom/v0.1.5/docs/assets/screenshots/mobile-wallet.png" alt="Wallet on a phone" width="240">
|
|
67
67
|
</p>
|
|
68
68
|
|
|
69
69
|
## Supported providers
|
|
@@ -81,7 +81,7 @@ Headroom holds the sign-in tokens for every AI account you connect. A hosted cop
|
|
|
81
81
|
- **Private:** the endpoint the provider's own app or CLI calls. It can change without notice.
|
|
82
82
|
- **Official:** a published API.
|
|
83
83
|
- **Enable providers** with `HEADROOM_ENABLED_PROVIDERS`. The default is all seven.
|
|
84
|
-
- **Evidence:** the [provider dossiers](https://github.com/amitray007/headroom/blob/v0.1.
|
|
84
|
+
- **Evidence:** the [provider dossiers](https://github.com/amitray007/headroom/blob/v0.1.5/docs/providers/README.md) record what is validated.
|
|
85
85
|
|
|
86
86
|
## How it works
|
|
87
87
|
|
|
@@ -104,7 +104,10 @@ flowchart LR
|
|
|
104
104
|
|
|
105
105
|
## Quick start
|
|
106
106
|
|
|
107
|
-
|
|
107
|
+
> [!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.5/DISCLAIMER.md) first.
|
|
109
|
+
|
|
110
|
+
Every way to install, update and remove Headroom is in [Install](https://github.com/amitray007/headroom/blob/v0.1.5/docs/operations/install.md).
|
|
108
111
|
|
|
109
112
|
### Installer
|
|
110
113
|
|
|
@@ -138,7 +141,7 @@ docker run -d --name headroom -p 8080:8080 \
|
|
|
138
141
|
ghcr.io/amitray007/headroom:latest
|
|
139
142
|
```
|
|
140
143
|
|
|
141
|
-
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.
|
|
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.5/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.5/docs/operations/releases.md).
|
|
142
145
|
|
|
143
146
|
### Docker on a Tailscale tailnet
|
|
144
147
|
|
|
@@ -150,7 +153,7 @@ cp .env.example .env # set TS_AUTHKEY and HEADROOM_PUBLIC_URL
|
|
|
150
153
|
docker compose up -d --build
|
|
151
154
|
```
|
|
152
155
|
|
|
153
|
-
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.
|
|
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.5/docs/operations/tailscale.md).
|
|
154
157
|
|
|
155
158
|
### From source
|
|
156
159
|
|
|
@@ -165,7 +168,7 @@ Open <http://localhost:8080>. In the checkout, `mise` sets data to `.data/` and
|
|
|
165
168
|
|
|
166
169
|
### The binary
|
|
167
170
|
|
|
168
|
-
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.
|
|
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.5/docs/operations/install.md).
|
|
169
172
|
|
|
170
173
|
```sh
|
|
171
174
|
headroom --open # serve on 127.0.0.1:8080 and open the dashboard
|
|
@@ -192,7 +195,7 @@ headroom service uninstall
|
|
|
192
195
|
| `HEADROOM_AUTH_SECRET_FILE` | same folder as the key, `headroom.auth-secret` | Session signing secret |
|
|
193
196
|
| `HEADROOM_CODEX_BIN`, `HEADROOM_CLAUDE_BIN`, `HEADROOM_GROK_BIN` | resolved on `PATH` | Absolute path of a sign-in CLI |
|
|
194
197
|
|
|
195
|
-
Every variable is listed in [Deployment and credential storage](https://github.com/amitray007/headroom/blob/v0.1.
|
|
198
|
+
Every variable is listed in [Deployment and credential storage](https://github.com/amitray007/headroom/blob/v0.1.5/docs/architecture/deployment.md).
|
|
196
199
|
|
|
197
200
|
## Security
|
|
198
201
|
|
|
@@ -202,7 +205,7 @@ Every variable is listed in [Deployment and credential storage](https://github.c
|
|
|
202
205
|
- Provider errors are mapped to fixed messages, so raw responses never reach logs or the browser.
|
|
203
206
|
- Demo Mode swaps in synthetic data for screenshots, and Privacy Mode blurs identities on screen.
|
|
204
207
|
|
|
205
|
-
Report a vulnerability privately as described in [SECURITY.md](https://github.com/amitray007/headroom/blob/v0.1.
|
|
208
|
+
Report a vulnerability privately as described in [SECURITY.md](https://github.com/amitray007/headroom/blob/v0.1.5/SECURITY.md).
|
|
206
209
|
|
|
207
210
|
## Development
|
|
208
211
|
|
|
@@ -221,7 +224,7 @@ packages/connectors/* One direct-HTTP client per provider
|
|
|
221
224
|
docs/ Product, architecture, provider research, decisions
|
|
222
225
|
```
|
|
223
226
|
|
|
224
|
-
Start with [CONTRIBUTING.md](https://github.com/amitray007/headroom/blob/v0.1.
|
|
227
|
+
Start with [CONTRIBUTING.md](https://github.com/amitray007/headroom/blob/v0.1.5/CONTRIBUTING.md) and the [documentation index](https://github.com/amitray007/headroom/blob/v0.1.5/docs/README.md).
|
|
225
228
|
|
|
226
229
|
## Support
|
|
227
230
|
|
|
@@ -229,9 +232,9 @@ Headroom is free, and there is no paid cloud version. If it saves you a surprise
|
|
|
229
232
|
|
|
230
233
|
## License
|
|
231
234
|
|
|
232
|
-
[MIT](https://github.com/amitray007/headroom/blob/v0.1.
|
|
235
|
+
[MIT](https://github.com/amitray007/headroom/blob/v0.1.5/LICENSE). Headroom also contains work from other projects under their own licenses: see [Third-party notices](https://github.com/amitray007/headroom/blob/v0.1.5/THIRD_PARTY_NOTICES.md) and [LICENSES/](https://github.com/amitray007/headroom/blob/v0.1.5/LICENSES/README.md). See also the [Disclaimer](https://github.com/amitray007/headroom/blob/v0.1.5/DISCLAIMER.md).
|
|
233
236
|
|
|
234
237
|
> [!NOTE]
|
|
235
238
|
> Headroom is an independent project, not affiliated with any provider listed above. Product names are trademarks of their owners.
|
|
236
239
|
>
|
|
237
|
-
> It is for personal self-hosted use. It reads your own accounts with your own credentials, and each provider's terms still apply.
|
|
240
|
+
> 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.
|