Create an API key
Open API keys in your account, give your key a name, and choose an expiry. Copy it when it appears; the full key is shown only once. You can revoke it on the same page.
Store the key as HYPERBOX_API_KEY in your secret manager or environment, then send it in the Authorization: Bearer header. Every valid account key, including existing keys, can create and delete Hyperboxes and read their credentials. Creating a Mac charges your authorized default card and starts a monthly subscription.
API responses contain passwords and connection URLs. Keep them out of shared logs and committed files. The curl examples print the response; run them in a private terminal.
Base URL: https://hyperbox.sh/api/v1/hyperboxes
Find and connect to your Hyperboxes
1. List your Hyperboxes
GET /api/v1/hyperboxes returns IDs, names, products, statuses, and creation timestamps. It contains no credentials. Use the stable ID to choose a machine; names may change or repeat.
curl --fail-with-body --silent --show-error \
-H "Authorization: Bearer $HYPERBOX_API_KEY" \
https://hyperbox.sh/api/v1/hyperboxes{
"hyperboxes": [
{
"id": "YOUR_HYPERBOX_ID",
"name": "Build Mac",
"product": "mac-mini",
"status": "running",
"createdAt": 1791244800000
}
],
"pagination": {
"nextCursor": null
}
}2. Fetch one machine’s credentials
GET /api/v1/hyperboxes/{id}/credentials returns the current connection details for a running, assigned Hyperbox. Set HYPERBOX_ID to an ID from the list response.
curl --fail-with-body --silent --show-error \
-H "Authorization: Bearer $HYPERBOX_API_KEY" \
"https://hyperbox.sh/api/v1/hyperboxes/$HYPERBOX_ID/credentials"3. Fetch credentials for your fleet
GET /api/v1/hyperboxes/credentials returns a hyperboxes array with metadata and credentials. Machines that are not ready have credentials: null and an unavailableReason; other machines in the page still return credentials.
curl --fail-with-body --silent --show-error \
-H "Authorization: Bearer $HYPERBOX_API_KEY" \
'https://hyperbox.sh/api/v1/hyperboxes/credentials?limit=100'Both list endpoints accept limit (1–100, default 100) and cursor. Follow pagination.nextCursor until it is null, even if a page is empty. Pass the cursor unchanged and URL-encode it. Retired Hyperboxes are omitted. An account with no Hyperboxes returns an empty array.
Add Macs and cancel billing
Add or authorize a default card in Billing. Adding a card is free. Website purchases require confirmation; an authenticated API purchase is the confirmation to charge that card and renew monthly until canceled.
GET /api/v1/hyperboxes/offers returns current macSku, monthlyPriceCents, currency, interval, and availability. Choose an available tier. Each POST /api/v1/hyperboxes creates one Mac. Send name, the offered macSku (omit it for the generic catalog), and an optional maxMonthlyPriceCentsto prevent a purchase above your price limit.
curl --fail-with-body --silent --show-error \
-X POST https://hyperbox.sh/api/v1/hyperboxes \
-H "Authorization: Bearer $HYPERBOX_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: build-mac-order-001' \
-d '{"name":"Build Mac","macSku":"m1-8gb","maxMonthlyPriceCents":4000}'Use a unique Idempotency-Key for each intended purchase. Retry with exactly the same key and body after a timeout; that returns the same purchase. A different body with the same key returns 409 idempotency_conflict. Inventory is held before charging. Sold-out requests return 409 out_of_stock without attempting payment.
A 202 response contains purchase.id, statusUrl, and the monthly price. Poll the status URL every few seconds. pending is processing; succeeded includes hyperboxId and credentialsUrl. For requires_action, have the account owner open authenticationUrl to authenticate with their bank, then poll the same purchase. Unfinished payments expire after 30 minutes.
curl --fail-with-body --silent --show-error \
-H "Authorization: Bearer $HYPERBOX_API_KEY" \
"https://hyperbox.sh/api/v1/hyperboxes/purchases/$PURCHASE_ID"A failed purchase includes errorCode. If allocation fails after payment, the subscription is canceled, the card payment is refunded, and any used account credit is restored. Create a new purchase with a new key only when you intend to try again. Reservations are free; activating an owned reservation uses this purchase flow with reservationId.
curl --fail-with-body --silent --show-error \
-X DELETE \
-H "Authorization: Bearer $HYPERBOX_API_KEY" \
"https://hyperbox.sh/api/v1/hyperboxes/$HYPERBOX_ID"DELETE /api/v1/hyperboxes/{id} returns 202 while cancellation runs. The Hyperbox shows terminating in the metadata list until Stripe confirms cancellation, then disappears. Repeating the deletion is safe. Its subscription is canceled immediately, future monthly charges stop, and canceled billing history stays in Billing. Deletion does not refund the current paid period.
Connection details
This is an example single-Hyperbox response. All passwords, IDs, and hosts below are placeholders.
{
"hyperbox": {
"id": "YOUR_HYPERBOX_ID",
"name": "Build Mac",
"product": "mac-mini",
"status": "running",
"createdAt": 1791244800000,
"credentials": {
"login": {
"username": "hyperbox",
"password": "EXAMPLE_PASSWORD"
},
"ssh": {
"host": "relay.hyperbox.sh",
"port": 22901,
"username": "hyperbox",
"password": "EXAMPLE_PASSWORD"
},
"screenSharing": {
"host": "relay.example.com",
"port": 15901,
"username": "hyperbox",
"password": "EXAMPLE_PASSWORD",
"url": "vnc://hyperbox:EXAMPLE_PASSWORD@relay.example.com:15901"
},
"rustdesk": {
"id": "123456789",
"password": "EXAMPLE_RUSTDESK_PASSWORD",
"url": "rustdesk://connection/new/123456789@rustdesk.example.com?password=EXAMPLE_RUSTDESK_PASSWORD&key=EXAMPLE_PUBLIC_KEY",
"server": {
"hbbsHost": "rustdesk.example.com",
"hbbsPort": 21116,
"hbbrHost": "rustdesk.example.com",
"hbbrPort": 21117,
"publicKey": "EXAMPLE_PUBLIC_KEY"
}
}
},
"unavailableReason": null
}
}| Field | Meaning |
|---|---|
| id / name / product / status | Stable Hyperbox ID, display name, cloud-pro or mac-mini, and current lifecycle status. |
| createdAt | Creation time as Unix milliseconds. API-key expiry times also use Unix milliseconds. |
| credentials.login | Account username and password for the machine. |
| credentials.ssh | Host, port, username, and password for direct SSH, or null when unavailable. |
| credentials.screenSharing | Screen Sharing host, port, username, password, and a credential-bearing vnc:// URL, or null. |
| credentials.rustdesk | RustDesk ID, password, deep-link URL, and server configuration, or null. The server field is null when not configured. |
| unavailableReason | null when credentials are returned; not_ready or no_longer_assigned when a bulk entry has no credentials. |
SSH-enabled physical Macs return their verified relay host, port, username, and password in credentials.ssh. Their Screen Sharing relay host and port are for VNC. Cloud machines return SSH details when available. Any unavailable connection method is null.
Connection URLs include passwords. Fetch fresh credentials when reconnecting after a reset or reassignment. API-key revocation blocks future API requests; it does not rotate credentials you have already retrieved or close existing desktop sessions.
A fleet script in Python
This example uses Python’s standard library, follows pagination, and retries temporary errors. It holds credentials in memory and prints only metadata. Add your connection tool where indicated.
import json
import os
import time
from urllib.error import HTTPError
from urllib.parse import urlencode
from urllib.request import Request, urlopen
BASE = "https://hyperbox.sh/api/v1/hyperboxes"
key = os.environ["HYPERBOX_API_KEY"]
def get_page(cursor=None):
params = {"limit": 100}
if cursor:
params["cursor"] = cursor
request = Request(
BASE + "/credentials?" + urlencode(params),
headers={"Authorization": "Bearer " + key},
)
for attempt in range(3):
try:
with urlopen(request, timeout=20) as response:
return json.load(response)
except HTTPError as error:
if error.code not in (429, 503) or attempt == 2:
raise RuntimeError(f"Hyperbox API returned HTTP {error.code}") from None
time.sleep(int(error.headers.get("Retry-After", 2 ** attempt)))
cursor = None
while True:
page = get_page(cursor)
for box in page["hyperboxes"]:
credentials = box["credentials"]
# Pass credentials to your connection tool here.
# Print only metadata; passwords and URLs stay in memory.
print(box["id"], box["name"], box["status"],
"available" if credentials else box["unavailableReason"])
cursor = page["pagination"]["nextCursor"]
if cursor is None:
breakErrors and limits
Keys expire after the chosen duration and allow 60 requests per minute per key. You can have up to 20 active keys. All API responses use Cache-Control: no-store.
{
"error": {
"code": "unauthorized",
"message": "Provide a valid, unexpired Hyperbox API key."
}
}| HTTP | What to do |
|---|---|
| 400 | Fix limit or cursor. For invalid_cursor, restart pagination. |
| 401 | Supply a valid key. Missing, invalid, expired, and revoked keys are rejected. |
| 402 | Save or authorize a valid default card in Billing before purchasing. |
| 404 | The Hyperbox does not exist or does not belong to the key’s owner. Refresh the list. |
| 409 | Check error.code: out_of_stock, price_changed, or idempotency_conflict for purchases; not_ready or no_longer_assigned for credentials. |
| 429 | Wait for the number of seconds in the Retry-After header. |
| 503 | The service is temporarily unavailable. Retry with a timeout and bounded backoff. |
Give your agent a skill
Install this skill in your agent’s skills directory and provide HYPERBOX_API_KEY through its environment or secret manager. The skill teaches it to select the right machine, fetch current credentials, and handle errors without exposing secrets.
For agents that discover project skills in .agents/skills, run this from your project directory:
mkdir -p .agents/skills/hyperbox-credentials
curl --fail --silent --show-error \
https://hyperbox.sh/skills/hyperbox-credentials/SKILL.md \
-o .agents/skills/hyperbox-credentials/SKILL.mdRead the full SKILL.md
---
name: hyperbox-credentials
description: Find and connect to a user's Hyperboxes, or create and delete Macs through the Hyperbox API when the user requests fleet changes.
---
# Hyperbox credentials
Use the Hyperbox API to identify the requested machine and retrieve current login, SSH, Screen Sharing, or RustDesk credentials. When the user requests a new Mac or deletion, use the purchase and deletion endpoints below.
## Authentication
- Read `HYPERBOX_API_KEY` from the environment or the user's secret manager. If it is missing, ask the user to create a key at https://hyperbox.sh/api-keys and configure it as a secret. Do not ask them to paste it into chat.
- Base URL: `https://hyperbox.sh/api/v1/hyperboxes`. Send `Authorization: Bearer <key>` over HTTPS. Every valid account key, including existing keys, can purchase Macs, delete Hyperboxes, and retrieve credentials for the owner's account. A purchase charges the authorized default card and starts monthly recurring billing.
- Keep the API key, passwords, and connection URLs out of chat, logs, screenshots, committed files, and shell history. Pass credentials directly to the connection tool or hold them in memory for the authorized task.
## Choose a machine
1. `GET /api/v1/hyperboxes` lists `hyperboxes` with `id`, `name`, `product`, `status`, and `createdAt`, without passwords. List metadata first.
2. List endpoints accept `limit` (1–100, default 100) and `cursor`. Follow `pagination.nextCursor` until it is `null`, including when a page is empty. URL-encode the cursor. Retired Hyperboxes are excluded.
3. Match the user's requested ID or name. Names can repeat or change; use the stable `id` for subsequent calls. If multiple machines match and the task does not disambiguate them, ask which one. Do not assume the first machine is the target.
4. `GET /api/v1/hyperboxes/{id}/credentials` returns `{ "hyperbox": { ...metadata, "credentials": ..., "unavailableReason": null } }` for a running, assigned machine.
5. For an explicitly requested fleet operation, `GET /api/v1/hyperboxes/credentials` returns paginated metadata and credentials together. Entries that are not ready have `credentials: null` and `unavailableReason`. Skip those entries and report their IDs/status without secrets.
## Use the response
`credentials` contains:
- `login`: macOS/Linux `username` and `password`.
- `ssh`: `{ host, port, username, password }` or `null`. Use only this endpoint for SSH. SSH-enabled physical Macs return their verified customer SSH relay endpoint. Other Macs return `ssh: null`; never use the Screen Sharing relay port for SSH.
- `screenSharing`: `{ host, port, username, password, url }` or `null`. The `vnc://` URL includes credentials and can open a Screen Sharing client.
- `rustdesk`: `{ id, password, url, server }` or `null`. `server`, when configured, contains `hbbsHost`, `hbbsPort`, `hbbrHost`, `hbbrPort`, and `publicKey`; `url` is a RustDesk deep link with credentials.
Unavailable connection methods are `null`; do not invent hosts, ports, passwords, or SSH access. Fetch credentials again when reconnecting after a reset or reassignment. Retrieval does not authorize unrelated changes to the remote machine.
## Create or delete a Mac
Only purchase or delete when the user requests it. A request to connect to an existing machine does not authorize buying a replacement.
1. The owner first adds or authorizes a default card at https://hyperbox.sh/billing. Adding a card is free; it authorizes website/API purchases and monthly renewals.
2. `GET /api/v1/hyperboxes/offers` returns the current catalog, available `macSku` values, and monthly USD prices in cents.
3. `POST /api/v1/hyperboxes` creates one Mac. Send JSON with `name`, an offered `macSku` (omit for the generic catalog), optional `maxMonthlyPriceCents`, and optional owned `reservationId`. Send a unique `Idempotency-Key` header for each intended purchase. The API request confirms the charge. Reservations themselves are free.
4. On a timeout or temporary error, retry exactly the same key and body. Never generate a new key to retry an uncertain request. `202` returns `purchase.id`, `statusUrl`, and the recurring price. Poll the status URL with the same bearer token every few seconds, within the shared rate limit.
5. `succeeded` includes `hyperboxId` and `credentialsUrl`. `requires_action` includes an `authenticationUrl`; ask the owner to open it and authenticate their card, then poll the same purchase. Unfinished payments expire after 30 minutes. `failed` includes `errorCode`; a new intended attempt needs a new key. Sold-out requests do not charge. Paid allocation failures cancel the subscription, refund cash, and restore account credits.
6. `DELETE /api/v1/hyperboxes/{id}` returns `202`. Cancellation is asynchronous and safe to repeat. Metadata shows `terminating` until Stripe confirms cancellation, then the machine disappears from the list. This ends future monthly charges and preserves canceled billing history; it does not refund the current paid period.
## Errors and retries
Errors are JSON: `{ "error": { "code": "...", "message": "..." } }`.
- `400`: fix request parameters; for `invalid_cursor`, restart pagination.
- `401`: the key is missing, invalid, expired, or revoked. Stop and ask the user to configure a valid key; do not retry the same key.
- `402`: the owner must save or authorize a valid default card in Billing.
- `404`: the Hyperbox is missing or inaccessible. Refresh the metadata list; do not probe other accounts.
- `409`: credentials are unavailable (`not_ready` or `no_longer_assigned`), inventory is sold out (`out_of_stock`), the price exceeds the cap (`price_changed`), or the same purchase key was used with a different body (`idempotency_conflict`). Inspect the code and fix the cause; do not blindly retry or raise the price cap.
- `429`: wait for `Retry-After` seconds. The limit is 60 requests/minute/key.
- `503`: retry with backoff. Use a request timeout and at most three attempts for temporary failures, then report the issue without secrets.
Full reference and examples: https://hyperbox.sh/docs