# Agent walkthrough: a bounded GPU rental

These are request examples, not an executed rental transcript. Any response described here is a shape, not evidence of a live machine or price. `$ARRAKIS_URL` is your Arrakis API origin without a trailing slash. See the current [OpenAPI document](/openapi.json) for complete schemas.

## 1. Create your account and credential

The simplest route is to sign in at [/console/](/console/). For API-only setup:

```sh
curl -X POST "$ARRAKIS_URL/v1/tenants" \
  -H 'Content-Type: application/json' -d '{"name":"Eval lab"}'
```

The response shape contains `id`, `name`, `created_at` and `bootstrap_secret`. Save the secret privately when it is returned: it is single-use and expires after 24 hours. Exchange it at `POST /v1/tokens` with `tenant_id`, `bootstrap_secret`, a token name and your chosen scopes. The bootstrap request has no bearer header. Default scopes are `read`.

An authenticated token-creation request requires `manage` and can grant only scopes the caller already holds. Keep account-management credentials separate from your agent. For the agent, create a token with `read` and `rent`, `spend_limit_usd`, `max_rental_hours` and a future `expires_at`. A child cannot escape its parent's remaining cap or maximum duration. Token secrets are returned once, stored hashed and revocable.

Store the agent token privately in `ARRAKIS_TOKEN`; never print it in logs or commit it. See [security](/docs/security.md) for the full boundaries.

## 2. Request funds

Request funds in the console. During early access our team confirms balances by hand. A deposit request is pending and does not increase your balance until an operator confirms it. Agents cannot credit themselves. There is no promised confirmation time.

## 3. Connect your agent or search directly

Connect Claude Code, Cursor or another MCP client to `$ARRAKIS_URL/mcp` with your bearer header. The [MCP guide](/docs/mcp.md) lists all eight tools and the local `arrakis mcp` alternative.

Direct API search requires `read`:

```sh
curl -H "Authorization: Bearer $ARRAKIS_TOKEN" \
  "$ARRAKIS_URL/v1/gpus?gpu_type=H100&max_price_per_gpu_hour=2"
```

Inspect current availability and the full machine price before renting. The search ceiling is per GPU-hour; a multi-GPU machine may cost more per hour. Use the returned opaque node id rather than guessing one. Public aggregate prices are available at `GET /v1/market/summary` without a token.

## 4. Rent with a deadline and a stable retry key

This request shape requires `rent`, confirmed funds, a valid node id and your actual SSH public key. It creates a billable rental if you execute it. Replace the placeholders first.

```sh
curl -X POST "$ARRAKIS_URL/v1/instances" \
  -H "Authorization: Bearer $ARRAKIS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"eval-01","node_id":"<node-id-from-search>","gpu_count":1,"ssh_public_key":"<your-ssh-public-key>","termination_hours":3,"idempotency_key":"eval-run-01"}'
```

The response shape includes `id`, `state` and `ssh_command` (which may be null while the machine starts). Capped tokens must set `termination_hours`, within their maximum rental duration. The machine's hourly price multiplied by this window reserves committed spend against the cap. A request exceeding the remaining cap is rejected with 402.

If the response is lost, retry with the same `idempotency_key`, not a new one. Keep a distinct key per intended rental. The same key returns the same machine rather than creating another.

## 5. Connect, save results and terminate

Read `GET /v1/instances/<instance-id>` until connection information is available. Use the returned SSH command from your terminal. The MCP tools manage compute; running an experiment and copying its results require your agent's own terminal tools.

Copy important results to storage you control, then terminate explicitly:

```sh
curl -X POST "$ARRAKIS_URL/v1/instances/$INSTANCE_ID/terminate" \
  -H "Authorization: Bearer $ARRAKIS_TOKEN"
```

For a removal schedule, `POST /v1/instances/$INSTANCE_ID/schedule-removal` takes `{"removal_scheduled_at":"<future-ISO-8601-time>"}`. Do not extend a job beyond its authorized budget. Do not rely on a zero account balance to stop an existing machine; retain its shutdown deadline and terminate it when done.

Independent hosts run these machines. There is no SLA. Keep regulated data off them and use volumes for checkpoints only where supported.