Resources for your agents.

Install the CLI#

spin is a Python tool installed with 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.

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.

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:

export SPIN_BROKER_TOKEN="cnv_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:

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#

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.

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#

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.

Two token scopes#

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.