# Set up with your agent

> Install the checkout-based RealHW client, authenticate, and verify read-only access.

Source: https://docs.realhw.dev/get-started/agent-setup/
Documentation index: https://docs.realhw.dev/llms.txt

## Set up with your agent

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.


## 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](https://docs.astral.sh/uv/getting-started/installation/).
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:

```sh
git clone git@gitlab.com: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:

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

```sh
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](https://docs.realhw.dev/guides/cli/#json-output-contract-v1).
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](https://docs.realhw.dev/llms.txt), retrieve individual
Markdown pages as needed, or download [/llms-full.txt](https://docs.realhw.dev/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](https://docs.realhw.dev/guides/gitlab-webhook/) 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.