hostbrr-vps

name	hostbrr-vps
description	Manage HostBRR VPS via the VirtFusion REST API — list servers, read specs/IPs, rebuild/reinstall the OS, power actions (restart/boot/shutdown/powerOff), SSH keys, ISO, VNC, rescue mode, resource packs, and task polling. Use whenever a task involves HostBRR servers, vps.hostbrr.com, "rebuild/reinstall a VPS", or a HostBRR API token. Teaches the correct client API base path (/api, NOT /api/v1), Bearer auth kept out of the transcript, the FQDN-hostname rebuild rule, and async task polling.
allowed-tools	Bash, Read

HostBRR VPS API

HostBRR VPS run on VirtFusion. Panel: https://vps.hostbrr.com. This skill drives the customer REST API.

The two things that waste the most time (read first)

1. The base path is https://vps.hostbrr.com/api — the customer API. It is NOT /api/v1/. /api/v1/* is VirtFusion's native admin API and returns 401 for a customer token. Endpoints are singular: /api/server, /api/account, /api/connect — not /api/v1/servers.
2. POST /server/{id}/build requires hostname to be an FQDN (e.g. host.example.com). A bare label like myserver returns 422 "The hostname provided is not valid".

Auth — keep the token out of the transcript

The API uses a Bearer token created in the HostBRR client area:

Authorization: Bearer <your_api_token>
Accept: application/json          # required on every request

Store the token in a secret manager rather than hardcoding it. If you use keys-keeper, keep it in an entry (e.g. hostbrr-admin-api) and inject it via a resolved curl config so it never lands in the transcript or ps:

CFG=$(mktemp); umask 077
cat > "$CFG" <<'EOF'
header = "Authorization: Bearer __KEYS:hostbrr-admin-api__"
header = "Accept: application/json"
header = "Content-Type: application/json"
EOF
keys resolve "$CFG"                                          # substitutes the real token into the file
curl -sS -K "$CFG" "https://vps.hostbrr.com/api/connect"     # 200 = token OK
# ... more curls with -K "$CFG" ...
shred -u "$CFG"                                              # always clean up

Errors: 401 bad/missing/expired token · 429 rate-limited (see X-RateLimit-*) · 503 maintenance (retry) · 422/409/404 return {"errors":[...]}.

Core recipes

Token / account check: GET /api/connect (200) · GET /api/account.

List servers (find an id by IP or name):

curl -sS -K "$CFG" "https://vps.hostbrr.com/api/server?results=200"
# data[] → id, name, hostname, memory, cpu, network.primary.ipv4[], ...

Rebuild / reinstall the OS (destructive — verify the target id + IP first):

B=https://vps.hostbrr.com/api; SID=<server-id>
curl -sS -K "$CFG" "$B/server/$SID/operatingSystemTemplates"   # pick templateId (confirm current IDs here — e.g. Ubuntu 24.04 has been 33, 22.04 = 10)
curl -sS -K "$CFG" "$B/account/sshKeys?results=50"             # pick sshKeys id to inject as root's authorized key
curl -sS -K "$CFG" "$B/server/$SID/swap"                       # optional swap values
curl -sS -K "$CFG" -X POST "$B/server/$SID/build" --data '{
  "method":"template","templateId":33,
  "hostname":"host.example.com",       # MUST be an FQDN
  "name":"<panel-name>","timezone":"Europe/London",
  "swap":512,"ipv6":false,"sshKeys":[<sshKeyId>] }'
# -> {"data":{"task":{"id":<taskId>,"status":"accepted"}}}

Then poll the task until it finishes:

curl -sS -K "$CFG" "$B/server/$SID/task/$TASKID"   # {"data":{...,"completed":true,"success":true}}

A rebuild changes the host key — ssh-keygen -R <ip> and re-scan afterwards. The SSH key you passed in sshKeys becomes root's authorized key on the fresh box.

Power actions (all POST, no body, return a task): /server/{id}/restart · /boot · /shutdown (graceful) · /powerOff (force).

Other endpoints: rename PUT /server/{id}/name · reset password POST /server/{id}/resetPassword · rescue POST /server/{id}/rescue · ISO GET/POST /server/{id}/iso(s) · VNC GET/POST /server/{id}/vnc · SSH keys GET/POST /account/sshKeys, DELETE /account/sshKeys/{id} · resource packs GET /resourcePack[...], create server POST /resourcePack/{packId}/{createId}.

Notes for the agent

• Async ops (build, power, vnc toggle, iso, rescue, resetPassword) return a task — poll GET /server/{id}/task/{taskId} (or /tasks) to confirm success rather than assuming.
• Paginated lists take ?results=N (1–200, default 20).
• 409 Conflict usually means the server is busy with another op (a build/restart already running).
• Before anything destructive (build/reinstall, powerOff, delete), verify the target server id AND IP — never wipe the wrong box.
• Full endpoint reference (request/response shapes, all status codes): references/api-spec.md.