# Resources for your agents.

> Create a wallet, set a budget, and give its token to your agent.

Rendered version: https://spin.inductionlabs.com/docs

## Install the CLI

`spin` is a Python tool installed with [uv](https://docs.astral.sh/uv/) from Spin’s package index. uv manages a private Python for it, so nothing else is required. Don’t have uv? `curl -LsSf https://astral.sh/uv/install.sh | sh`.

```sh
uv tool install spin --index https://spin.inductionlabs.com/cli/simple/
spin --help
```

In interactive sessions `spin` checks for a new release once a day and upgrades itself through uv before running your command. Run `spin update` or `uv tool upgrade spin` to update now, or set `SPIN_NO_UPDATE=1` to opt out. Non-interactive runs, including agent sandboxes, never auto-update.

## Create a wallet

Install the Spin or Frontier MLE CLI. Keep your account key on your host or in CI. Wallets expire after one day unless you pass `--expires-seconds`; use `0` for no expiry, up to 30 days otherwise.

```sh
export SPIN_BASE_URL="https://api.spin.inductionlabs.com/v1"
export SPIN_API_KEY="cnv_live_…"
spin wallet create --name experiment --budget 1 --request-id experiment-001
```

## Use it from the agent

Give the wallet token to your agent. The CLI defaults to hosted Spin:

```sh
export SPIN_BROKER_TOKEN="spin_agent_…"
spin budget status
spin compute offers
spin compute create --provider modal --request-id training-001 \
  --spec '{"gpu":"H100","gpus":1,"cpus":8,"memory_gib":32,"max_seconds":60}'
spin compute exec RESOURCE_ID 'nvidia-smi'
spin compute stop RESOURCE_ID
```

Compute is prepaid. Releasing it early does not refund unused time.

## Extend or stop compute

Extend a running SF or Vast resource within its limits and wallet budget:

```sh
spin compute extend RESOURCE_ID --seconds 600 --request-id extension-001
```

Modal sandboxes cannot extend their original timeout. Stopping a Vast rental destroys it and its disk, so save output first.

## Manage wallets

```sh
spin wallet list
spin wallet resources WALLET_ID
spin wallet close WALLET_ID
```

Closing a wallet stops its resources and returns unused credit after settlement. Agents can request cleanup with `spin run close`.

## Inference

Agents call models through an OpenAI-compatible endpoint billed to the same wallet. `spin openrouter key create` returns the wallet token as the API key and `https://api.spin.inductionlabs.com/v1` as the base URL; `GET /v1/models` lists the models this installation allows.

```sh
curl "https://api.spin.inductionlabs.com/v1/chat/completions" \
  -H "Authorization: Bearer $SPIN_BROKER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reply-001" \
  -d '{"model":"MODEL_ID","messages":[{"role":"user","content":"hello"}],"max_tokens":256}'
```

Requests are non-streaming and need a stable `Idempotency-Key`; retrying with the same key returns the same completion without a second charge. Each request reserves its worst-case price up front and settles to the provider's reported cost.

## HTTP API

```sh
curl "https://api.spin.inductionlabs.com/v1/wallets" \
  -H "Authorization: Bearer $SPIN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: experiment-001" \
  -d '{"name":"experiment","budget_cents":100,"expires_in_seconds":86400}'
```

Reuse the same idempotency key and body on retry. Account amounts are USD cents; resource amounts are decimal USD strings. Every endpoint is described in the [API reference](https://spin.inductionlabs.com/docs/api).

## Two token scopes

| Token | Access | Location |
| --- | --- | --- |
| Account key | Wallets and account resources | Host or CI |
| Wallet token | Compute and models within its budget | Agent sandbox |

## Self-hosting

Run the Go API and resource gateway with Docker Compose and Postgres. Set `SELF_HOST_API_KEY` for CLI/API access, then point `SPIN_BASE_URL` and the agent’s `SPIN_BROKER_URL` at your installation. Your runner handles agent execution and evaluation. For local development with mock sign-in, run `scripts/dev.sh up` from the repository.

## Also available

- [API reference (Markdown)](https://spin.inductionlabs.com/docs/api.md)
- [OpenAPI specification](https://api.spin.inductionlabs.com/openapi.json)