Oleks
cbcf122422
Haiku ops agent + 3 tools (nbshell expect+PTY admin-shell driver, nbapi read-only HTTP client, nb-substituters guarded cache manager) + 2 skills (nixbuild-settings, nixbuild-usage). Encodes the two-control-surface model and the path-style-substituter-URL gotcha.
92 lines
3.0 KiB
Markdown
92 lines
3.0 KiB
Markdown
---
|
|
name: nixbuild-usage
|
|
description: |
|
|
Report nixbuild.net account usage and cost posture — remaining free build
|
|
time, billable CPU-seconds over a date range, build history (success/fail/
|
|
discarded), output NAR size, and stored size. The account is metered, so
|
|
this is the cost-visibility skill. Reads come from the HTTP API (nbapi tool,
|
|
no PTY needed) plus the shell's `usage` command for the live free-time
|
|
counter. Trigger on "nixbuild usage", "how much build time left", "nixbuild
|
|
billing", "nixbuild storage", "nixbuild build history", "am I out of free
|
|
build time", "nixbuild cost".
|
|
disable-model-invocation: false
|
|
allowed-tools: Bash, Read
|
|
---
|
|
|
|
# nixbuild-usage — metered account usage & cost
|
|
|
|
Owning agent: `nixbuild:ops`. nixbuild bills CPU-time beyond a monthly free
|
|
tier; this skill answers "where do I stand" without touching settings. Most of
|
|
it is the read-only HTTP API via **`nbapi`** (`${CLAUDE_PLUGIN_ROOT}/bin`), which
|
|
needs no PTY. The live free-time counter comes from the shell banner / `usage`.
|
|
|
|
## Quick posture
|
|
|
|
```bash
|
|
nbapi summary
|
|
```
|
|
|
|
Returns (example shape):
|
|
|
|
```json
|
|
{
|
|
"build_count": 19, "running_build_count": 0,
|
|
"discarded_build_count": 1, "failed_build_count": 1,
|
|
"successful_build_count": 17,
|
|
"total_cpu_seconds": 27401, "billable_cpu_seconds": 20963,
|
|
"total_duration_seconds": 2708.06, "wall_time_seconds": 48398.44,
|
|
"total_output_nar_size_kilobytes": 786691
|
|
}
|
|
```
|
|
|
|
Key fields: `billable_cpu_seconds` (what you pay for), `successful/failed/
|
|
discarded_build_count`, `total_output_nar_size_kilobytes`.
|
|
|
|
## Remaining free build time (live)
|
|
|
|
The free-tier counter is only in the shell, not the HTTP API:
|
|
|
|
```bash
|
|
nbshell 'usage'
|
|
```
|
|
|
|
The shell login banner also prints it, e.g. `Free build time left: 25:00:00
|
|
(hh:mm:ss)` — it resets at the start of each month. When spent, the banner
|
|
reads `You have no free build time left` and further builds are billed.
|
|
|
|
## Billable CPU over a date range
|
|
|
|
```bash
|
|
nbapi usage --from 2026-06-01 --to 2026-06-30
|
|
```
|
|
|
|
## Recent build history
|
|
|
|
```bash
|
|
nbapi builds --limit 20
|
|
```
|
|
|
|
Each entry carries id, status, drv path, timing — useful to spot a runaway or
|
|
repeatedly-failing build burning CPU. For one build's detail: `nbapi raw
|
|
/builds/<id>`; for a shareable web link: `nbapi raw /builds/<id>/url`.
|
|
|
|
## Stored size
|
|
|
|
`Storage used:` appears in the shell banner (`nbshell 'usage'`), and
|
|
`total_output_nar_size_kilobytes` in `nbapi summary` approximates output volume.
|
|
|
|
## Reporting
|
|
|
|
Lead with the two numbers that matter: **free time left** and **billable
|
|
CPU-seconds** (this month). Add fail/discard counts only if non-trivial (a high
|
|
`failed`/`discarded` ratio means wasted spend — flag it). Convert CPU-seconds to
|
|
hours for readability (`/3600`). Keep it to a few lines unless asked for the
|
|
full history.
|
|
|
|
## Token
|
|
|
|
`nbapi` reads the bearer token from `$NIXBUILD_API_TOKEN`, else `pass show
|
|
infra/nixbuild/api-token` (override the entry with
|
|
`$NIXBUILD_API_TOKEN_PASS_ENTRY`). The read-only API needs only the `:read`
|
|
scopes; a broad token works but is more than required.
|