Hyperbox API Docs

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 key has the credentials:read scope and can read credentials for all Hyperboxes owned by your account.

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.

List Hyperboxes · shell

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $HYPERBOX_API_KEY" \
  https://hyperbox.sh/api/v1/hyperboxes

List response · JSON

{
  "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.

Fetch credentials · shell

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.

Fetch fleet credentials · shell

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.

Connection details

This is an example single-Hyperbox response. All passwords, IDs, and hosts below are placeholders.

Single credentials response · JSON

{
  "hyperbox": {
    "id": "YOUR_HYPERBOX_ID",
    "name": "Build Mac",
    "product": "mac-mini",
    "status": "running",
    "createdAt": 1791244800000,
    "credentials": {
      "login": {
        "username": "hyperbox",
        "password": "EXAMPLE_PASSWORD"
      },
      "ssh": null,
      "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.

Physical Macs currently expose Screen Sharing and RustDesk; ssh is null. 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.

fetch_hyperboxes.py

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:
        break

Errors 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 credential API responses use Cache-Control: no-store.

Error response · JSON

{
  "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.
404	The Hyperbox does not exist or does not belong to the key’s owner. Refresh the list.
409	The requested Hyperbox is not ready or is no longer assigned. Check the dashboard.
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.

Download SKILL.md

For agents that discover project skills in .agents/skills, run this from your project directory:

Install the skill · shell

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.md

Read the full SKILL.md

hyperbox-credentials/SKILL.md

---
name: hyperbox-credentials
description: Find a user's Hyperboxes and fetch current connection credentials through the Hyperbox API when connecting to or working on their remote machines.
---

# Hyperbox credentials

Use the read-only Hyperbox API to identify the requested machine and retrieve its current login, SSH, Screen Sharing, or RustDesk credentials.

## 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. Keys have the `credentials:read` scope and cover the owner's Hyperboxes.
- 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. Physical Macs currently return `ssh: null`; their Screen Sharing relay port does not accept 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.

## 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.
- `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`). Check the dashboard state; do not attempt connection using stale credentials.
- `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