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