# Spawn Setup Skill

Use this skill to help a user configure a tinkerer Hermes agent on Spawn.

Base URL:

```text
https://spawn.graybeam.tech
```

## What this skill may do

- Ask the user for a desired agent name, or omit it so Spawn autogenerates one.
- Ask whether the default tinkerer model is acceptable.
- Ask for a positive budget cap.
- Submit only a setup draft to Spawn for validation.
- Send the user to a Spawn-hosted confirm URL.
- Poll setup status after the user confirms.

## What this skill must not do

- Do not ask for, accept, transmit, store, or log the user's OpenRouter key.
- Do not ask for, accept, transmit, store, or log payment-card data.
- Do not submit DigitalOcean, DNS, OIDC, WebUI, gateway, SSH, Cloudflare, database, or job-runner settings.
- Do not provision anything directly. There is no setup-agent deploy action.
- Do not invent endpoints named `deploy` or `submit_secret`.

## OpenRouter funding

Tinkerer agents always use managed key minting: Spawn creates a budget-limited agent-scoped OpenRouter key and deploys only that scoped key.

The default funding source is Spawn-managed OpenRouter access, so a user can get going immediately without entering a key.

On the trusted Spawn confirm page, the human may optionally choose to use their own OpenRouter management key. Spawn uses that key once to mint the scoped budget-limited agent key. The setup agent must never collect that key, and tinkerer does not support raw BYOK passthrough.

## Access model

`/skill`, `POST /spawn/setup/agents`, and `GET /spawn/setup/agents/:agent_id` are public bootstrap/discovery routes.

Thread, draft, quote, and status routes require HTTP bearer authentication with the token returned by registration. The authorization scheme is case-sensitive and must start with the literal word `Bearer` using a capital `B`.

Store the returned bearer token privately. Spawn returns it at registration and stores only a token hash internally.

Setup-agent bearer tokens expire after 24 hours. Unconfirmed setup threads also expire after 24 hours. Quote confirm URLs expire after 15 minutes.

## Register a setup agent

```http
POST /spawn/setup/agents
content-type: application/json
```

Body:

```json
{"name":"YourSetupAgentName"}
```

Success returns:

```json
{"data":{"agent_id":"...","name":"YourSetupAgentName","token":"...","registered_at":"...","expires_at":"..."}}
```

## Discover public setup-agent metadata

```http
GET /spawn/setup/agents/:agent_id
```

This returns non-secret public metadata and never returns bearer tokens.

## Create a setup thread

```http
POST /spawn/setup/threads
authorization: Bearer ...
content-type: application/json
```

Success returns a durable `thread_id`.

## Submit a setup draft

```http
POST /spawn/setup/threads/:thread_id/draft
authorization: Bearer ...
content-type: application/json
```

Body:

```json
{"draft":{"name":"optional-agent-name","model":"deepseek/deepseek-v4-pro","budget_cap":25}}
```

Allowed draft fields are exactly `name`, `model`, and `budget_cap`.

Spawn validates the draft through the tinkerer profile:

- provider: `openrouter`
- key mode: `managed`
- storage backend: `local`
- default model: `deepseek/deepseek-v4-pro`
- gateway, WebUI, and OIDC are Spawn-managed invariants

Validation errors are returned to the caller so the setup agent can re-ask the user.

## Request a quote and confirm URL

```http
POST /spawn/setup/threads/:thread_id/quote
authorization: Bearer ...
```

A quote requires a valid draft. Success returns a short-lived Spawn-hosted confirm URL. The human chooses Spawn-managed funding or enters an OpenRouter management key only on that trusted Spawn page.

If the quote has an amount due, the trusted Spawn page sends the human through Stripe Checkout first. Checkout creates a monthly subscription. The setup agent never handles payment-card data, Stripe secrets, or webhook payloads.

## Poll status

```http
GET /spawn/setup/threads/:thread_id/status
authorization: Bearer ...
```

Status responses never include OpenRouter keys or raw confirm tokens.

Status responses are intentionally minimal. They include the thread id, setup status, payment status, public agent hostname/URL when available, thread expiry, and safe next-action text. They do not include host IPs, OpenRouter key hashes, provisioning stages, last errors, or other operator diagnostics.

Operator diagnostics are available only to Hub-authenticated Spawn admins at:

```http
GET /admin/setup/threads/:thread_id/diagnostics
```