Resources for your agents.
Create a wallet, set a budget, and give its token to your agent.
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
Fixed prices for evaluations#
A wallet with static pricing sees one fixed price per GPU model instead of each provider’s, so an agent’s budget buys the same compute whatever the market does. --static-pricing alone uses Spin’s GPU price index: the median on-demand price of each model across providers, per GPU-hour. Offers name the model in gpu_model, and H100s are priced by form factor: H100 SXM, H100 PCIe and H100 NVL each have their own price, and an H100 whose provider doesn’t say which it is lists as H100 (unknown form factor) at the SXM price. Pass a table of your own as JSON or @file; a bare H100 in it covers every form factor the table doesn’t name.
spin wallet create --name eval-001 --budget 20 --static-pricing --request-id eval-001
spin wallet create --name eval-002 --budget 20 --request-id eval-002 \
--static-pricing '{"gpu_hour_usd": {"H100": 3, "A100": 1.5}}'The wallet’s offers, resources and budget are shown in these prices, and its budget is spent in them. Your account still pays what the providers actually cost: the wallet draws more credit when that runs ahead of its prices and returns what is left at close, so a $20 wallet can cost more or less than $20. Wallet lists show that real cost as cost_usd. GPUs missing from the table are not offered; CPU-only machines and model calls count at their real cost.
Use it from the agent#
Give the wallet token to your agent. The CLI defaults to hosted Spin:
export SPIN_BROKER_TOKEN="spin_agent_…"
spin budget status
spin compute offers
spin compute create --provider vastai --request-id training-001 \
--spec '{"offer_id":"OFFER_ID_FROM_OFFERS","max_seconds":600}'
spin compute exec RESOURCE_ID 'nvidia-smi'
spin compute stop RESOURCE_IDA new lease starts as checking while Spin confirms the machine answers commands and its GPUs work; poll spin compute status until it is running. Nothing is charged until the check passes. A machine that is not up within 20 minutes, or that its provider reports dead, is destroyed and its hold returned to the wallet.
Once running, compute is prepaid. Releasing it early does not refund unused time.
Copy files and folders#
Use spin s5cmd for direct transfers to your wallet’s R2 storage. It fetches temporary credentials automatically; file bytes bypass Spin’s servers. s3://spin/ means your wallet’s private folder. Quote wildcards.
spin s5cmd cp ./model.bin s3://spin/checkpoints/ spin s5cmd cp 's3://spin/checkpoints/*' ./checkpoints/ spin s5cmd sync ./dataset/ s3://spin/dataset/ spin s5cmd ls s3://spin/
First use installs a pinned, checksum-verified s5cmd binary. Use spin s5cmd --install to prepare an image, and spin s5cmd cp --help for copy options. Inline compute upload/download are limited to 512 KiB.
To copy from a GPU VM without giving it your wallet token, export a session for just the results folder. Install Spin on the VM, then:
spin transfer credentials --prefix results --out session.json spin compute upload RESOURCE_ID ./session.json /tmp/spin-s3.json spin compute exec RESOURCE_ID 'spin s5cmd --session /tmp/spin-s3.json cp /workspace/model.bin s3://spin/' spin s5cmd cp s3://spin/results/model.bin ./model.bin
Session files contain temporary secrets; keep them private and remove them when finished. Add --read-only for input-data access. Sessions last 8 hours by default and at most, capped by wallet expiry; use --expires-seconds for shorter sessions. Copies do not refresh credentials mid-command; reissue and retry if they expire. Download results before closing the wallet: closure deletes its objects and incomplete uploads. Existing sessions remain valid until expiry; Spin automatically cleans up late uploads. Files expire after two days; deletion is asynchronous.
For another S3 client, call POST /v1/transfer/credentials with {} or a relative prefix, then use the returned endpoint, full S3 path, access key, secret and session token. See the API reference. This replaces per-file URL signing.
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 need a stable Idempotency-Key; retrying a completed non-streaming request with the same key returns the same completion without a second charge. Set stream: true to receive server-sent events (a streamed request cannot be replayed; use a new key). 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#
| 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.