Skip to content
RealHW

Python client and CLI

The realhw-cli repository provides a Python REST client and the realhw command. Install from a checkout with Python 3.11 or newer:

Terminal window
cd realhw-cli
uv tool install .
realhw hardware labels

The package is not yet published on PyPI. Available commands list hardware labels and project runners, and reserve, list and close interactive console sessions. Remote one-shot image execution and artifact retrieval are not exposed by this client yet.

Authenticate

Section titled “Authenticate”

For automation, inject REALHW_API_TOKEN from your secret manager. Create the token in Settings → API keys with the permissions and project restriction you need. REALHW_API_KEY is also accepted. Do not include tokens in command arguments or prompts.

For an interactive terminal:

Terminal window
realhw auth login
realhw consoles list

Login opens RealHW in your browser. Sign in, review the requested permissions, confirm that the displayed code matches your terminal, then authorize the CLI. Never approve a code sent by someone else. For SSH or a terminal without a browser, use realhw auth login --no-browser and open the printed URL on another device.

This is the OAuth device authorization flow (RFC 8628), using the public client ID realhw-cli. The default permissions are runners:read and consoles:read. Access lasts 24 hours; log in again after expiry. No refresh token is issued. The credential appears in Settings → API keys, where you can revoke it.

Terminal window
realhw auth login --scope consoles:read --scope consoles:write --project-id <project-uuid>
realhw auth status
realhw auth logout

Logout forgets the local credential; it does not revoke remote access or unset environment tokens. Status shows local metadata without exposing the token. Saved credentials use private files (0600) in ~/.config/realhw, separated by API origin. This storage requires macOS/Linux file permissions; other platforms can use environment tokens.

Reserve a console

Section titled “Reserve a console”
Terminal window
realhw runners list --account-id <account-uuid>
realhw consoles reserve --account-id <account-uuid> --project-id <project-uuid> \
  --label arch:x86_64 --label kvm --image ubuntu:24.04 --ttl 3600
realhw consoles list
realhw consoles close <session-uuid> --reason 'Finished debugging'

Use labels returned by hardware labels. Reservation may allocate billable hardware. This creates an interactive shell reservation, not a one-shot image job. Console WebSocket streaming remains available through the web app.

Scripts and Python

Section titled “Scripts and Python”

Commands return JSON on stdout and errors on stderr, with nonzero exit codes on failure. Use --compact before the subcommand for single-line JSON. Login instructions go to stderr. There are no hidden confirmation prompts.

import os
from realhw_cli import RealHWClient


with RealHWClient(token=os.environ["REALHW_API_TOKEN"]) as client:
    sessions = client.consoles()

REALHW_API_URL overrides the default https://realhw.dev. Existing ingress/IP access restrictions still apply; tokens do not bypass them. HTTPS is required except for loopback development. Redirects are disabled and mutations are never automatically retried. After a timeout, inspect state before repeating a reservation.

Browser login requires the matching server OAuth endpoints and /device page. An older server returns 404; use an API token until that server is upgraded.