# WorkerWizard agent quickstart

WorkerWizard is an **auth and payment upgrade over managed isolated workspaces**, not a new hypervisor and not a root SSH VPS catalogue.

- Underneath, when enabled: one isolated, non-root Linux workspace per tenant on Cloudflare Sandbox/Containers (microVM isolation). Prepaid hourly rental of a fixed size.
- Access: authenticated PTY or exec, supported runtimes, and HTTP services — not root SSH.
- Files: documented snapshot/restore of project files to object storage (R2). R2 is not a POSIX block device; do not keep databases or package trees on a naive object-storage mount. Memory and unsaved ephemeral disk are not guaranteed across sleep, restart, or replace.
- Above: wallet signatures (SIWE) and, when enabled, x402 USDC on Base so an agent can rent and operate a workspace without a human passing through a web UI checkout.
- A human dashboard talks to the same API and is optional.

This document describes the actual control plane at https://workerwizard.com. It does not claim WorkerWizard is the first agentic cloud, and it does not claim that onboarding is free of usage rules or that upstream infrastructure is permissionless. Non-root alone is not a security boundary.

## What is live today

| Capability | Status |
|---|---|
| Public API and this document | Live |
| OpenAPI schema at `/openapi.json` | Live |
| SIWE wallet authentication | Live (proves ownership only) |
| Workspace *request* records, budgets, audit log | Live |
| x402 USDC settlement | **Not enabled.** `accepts` is empty. Do not send funds. |
| Starting a Sandbox, PTY, exec, HTTP service, or snapshot restore | **Not enabled.** Runtime bindings are not connected. |

`GET /api/runtime` is the source of truth for readiness. If `payments.enabled` or `compute.canProvision` is false, treat any "success" that claims a paid or running workspace as an error.

## 1. Authenticate

```
POST /api/auth/nonce
POST /api/auth/verify    {"message":"<SIWE text>","signature":"0x..."}
GET  /api/session
```

Use the nonce, domain, URI, and statement returned by `/api/auth/nonce`. The signature must be from the wallet that will own the workspaces. It does not authorize a transfer.

Subsequent requests should include the `ww_session` cookie from verify.

## 2. Read the catalog

```
GET /api/catalog
```

Plans are `nano`, `micro`, and `small` (isolated workspaces, no root SSH). The customer term is `hourly`. Rates are unpublished and are not a live price.

## 3. Request a workspace

```
POST /api/workspaces
{"planId":"nano","billingTerm":"hourly","name":"optional","budgetHours":24}
```

This only records a request for the signing wallet. The response includes `provisioned: false` and `charged: false`. There is no running sandbox and no PTY yet. `/api/machines` is a compatibility alias for the same records.

## 4. Lifecycle

```
POST /api/workspaces/:id/start
POST /api/workspaces/:id/exec
POST /api/workspaces/:id/terminal
POST /api/workspaces/:id/stop
POST /api/workspaces/:id/destroy
GET  /api/workspaces/:id/events
```

`start` is implemented and currently returns a blocked workspace with `provisioned: false` and `charged: false`. `exec` and `terminal` return 409 with `executed`/`started` false. None of these will invent a running sandbox or a root SSH host.

## 5. x402 payments (not live)

```
GET  /api/x402
POST /api/x402/pay
```

When settlement is live, start and provision calls are intended to use x402 (USDC on Base) so an agent can pay the prepaid hourly term in-band. Today:

- `enabled` is false and `accepts` is `[]`.
- No pay-to address is published.
- `POST /api/x402/pay` is rejected; `paid`, `charged`, and `provisioned` are false.
- Sending a payment header or payload cannot bypass the disabled runtime.

Do not send USDC or any other asset to this service until `/api/runtime` reports `payments.enabled: true` and `/api/x402` lists an `accepts` entry you have verified.

## Discovery

- Quickstart: https://workerwizard.com/docs/agent.md
- This file is also linked from https://workerwizard.com/llms.txt
- OpenAPI 3.1: https://workerwizard.com/openapi.json
