Set up with your agent

Give this prompt to your coding agent to install the CLI and verify access. Repository access is required during early access.

Preview prompt

Set up the RealHW CLI on this machine using https://docs.realhw.dev/get-started/agent-setup/index.md as the canonical guide. Read it first and follow its pinned checkout installation instructions; the CLI is not published on PyPI and repository access is required. Preserve existing checkouts and credentials. Use an existing environment token without displaying it, or guide me through browser login with read-only permissions. Never ask me to paste credentials into this conversation. Verify the CLI version, supported operations, and current hardware with JSON commands. Report any access or setup blocker clearly. Stop after verification; do not reserve hardware or start workloads.

Setup instructions

Before you start

The RealHW Python CLI is in early access. It is not published on PyPI. Install from the authorized GitLab repository below; do not install a similarly named package from a package index. Your GitLab identity must have access to the private repository. If access is denied, request access from your RealHW administrator and stop setup.

You need Git, Python 3.11 or newer, and uv. Saved credentials require macOS/Linux file permissions. On other platforms, use an environment token. Your network must also be allowed through the RealHW ingress rules.

Install the verified checkout

This guide targets CLI 0.4.0, commit 4ca1bc7472b7d9aafb087e416f85eb8a3b9d9256. Use a new directory; preserve existing checkouts and uncommitted work. Use your normal GitLab SSH authentication:

git clone [email protected]:pvinci/realhw-cli.git realhw-cli-0.4.0
cd realhw-cli-0.4.0
git switch --detach 4ca1bc7472b7d9aafb087e416f85eb8a3b9d9256
uv tool install .
realhw --version

Expected version: realhw, version 0.4.0. If your installation uses HTTPS GitLab authentication, use https://gitlab.com/pvinci/realhw-cli.git with your configured credential helper. Never embed a GitLab token in a clone URL or prompt.

For an existing uv-managed Python client, use uv tool install --force . from the verified checkout to update it. First inspect uv tool list and command -v realhw. If realhw is a different program, such as the older Rust CLI, preserve it and resolve the executable conflict before proceeding. If the executable is missing from PATH, follow uv’s installation output or run uv tool update-shell and reopen your terminal.

Authenticate

Use an existing REALHW_API_TOKEN (or REALHW_API_KEY) if the user has already supplied one through the environment. Do not print its value, read it into a prompt, or paste it into command arguments. The token needs runners:read for hardware discovery.

Otherwise, use browser login:

realhw auth login

Default login permissions are read-only: runners:read consoles:read. The user signs in on the web page, checks the displayed device code against the terminal, and approves access. For a headless terminal, run realhw auth login --no-browser and give the user the displayed verification URL and code. The user completes approval; the agent should not approve on their behalf. Login expires after 24 hours and can be revoked in Settings.

Environment tokens take precedence over saved browser login. If an environment token is expired or insufficiently scoped, replace it through the user’s secret management or explicitly unset it before choosing browser login. Never silently change API origin or reuse a token against a different service.

Verify without allocating hardware

realhw --version
realhw auth status --json
realhw capabilities --json
realhw hardware list --json

auth status checks local configuration only. A successful hardware list request verifies authenticated access with runners:read. capabilities is public and does not by itself verify authentication. Both discovery responses have schema_version: 1. An empty labels array is a valid current fleet report, not an authentication failure. Report the CLI version, API origin, verification results, and any blocker without including credentials. Stop here. Reserve hardware only when the user requests it.

When setup fails

Failure	Next step
GitLab clone denied or repository not found	Check the user’s GitLab identity and repository membership. Do not substitute another package.
CLI missing or wrong version	Check PATH, `command -v realhw`, and `uv tool list`; preserve unrelated installations.
Exit 3, HTTP 401	Supply a valid token or log in again. Check for an expired environment token overriding login.
Exit 3, HTTP 403	Check token scopes and project restrictions. If ingress blocks the request, ask the RealHW administrator to check network access.
Exit 4	Check DNS, connectivity, API origin, and request timeout.
HTTP 404	Confirm the API origin and whether that server supports the requested endpoint.
JSON/protocol error or an HTML response	Check proxy/ingress access and the selected API origin.

Use --json for automation; successful results go to stdout, errors to stderr. See the JSON contract and exit codes. Do not automatically retry a reservation after a timeout: inspect state first to avoid allocating twice.

What is available

The Python CLI discovers hardware and supported operations, lists project runners, and reserves, lists, and closes interactive console sessions. CLI 0.4.0 adds preview image-workload submission, status, cancellation, logs and artifact retrieval when the server advertises those operations. Cloud-init and Compose remain unsupported. Read realhw capabilities --json for the server’s current contract.

Hardware is discovered live through the API; documentation examples do not promise current capacity or that multiple labels coexist on one available machine.

For agents reading documentation, start with /llms.txt, retrieve individual Markdown pages as needed, or download /llms-full.txt for the complete published documentation. These files are regenerated with every docs build.

Runner event onboarding

After installing CLI 0.4.0, use realhw capabilities --json to check for runners.webhook.inspect and runners.webhook.configure. These operations inspect and configure GitLab events for an existing registration; they are separate from creating a runner. Follow GitLab event onboarding for preview/apply, required scopes, injected credentials, audit IDs, and delivery checks. The installation pin above includes these commands; check live capabilities to verify that the matching backend has been deployed.