# WAVE Sandbox — safe execution front door

WAVE Sandbox lets an agent propose an untrusted shell command, receive the EXACT filesystem diff plus a
tamper-evident receipt BEFORE anything runs, approve that specific diff, and have WAVE execute it in
containment (in-memory filesystem, network off, execution limits). Untrusted input never reaches a real
host shell, disk, or network.

## Contract (preview → approve → apply)
- POST /v1/sandbox/preview  {"command": "...", "files"?: {path: contents}}
    → {tier, wouldExec, fsDiff, receipt:{id, ...hashes}}   (metered: wave_sandbox_preview)
- POST /v1/sandbox/apply    {"command": "...", "approval": "<receipt.id from preview>"}
    → {approved, tier, exitCode, stdout, fsDiff, receipt}   (metered: wave_sandbox_exec)
    Fail-closed: the approval token must equal the receipt id computed for THIS exact command+files.
- GET  /v1/sandbox/receipt/{id}  → {receipt}   (tenant-isolated, hash-only, 7d retention)

## Tiers
- EDGE     core shell (echo, grep, jq, awk, sha256sum, …) — runs at the edge.
- NODE     contained sqlite3 (sql.js) and js-exec (QuickJS) — runs on the Node host.
- ESCALATE git/build/docker — never auto-run; routed to an isolated Firecracker tier.

## Auth
Gateway-trust: requests carry x-wave-gateway-secret (constant-time checked) and reach the spoke only
through the WAVE API funnel. A missing or unset secret fails closed.

## Endpoints
- Production contract: https://api.wave.online/v1/sandbox   (availability: pending-launch)
- Human playground + this discovery surface: sandbox.wave.online
- Machine manifest: /.well-known/wave-capability.json
- Standard agent surfaces (via the WAVE chassis): /.well-known/agent-card.json, /openapi.json, /skill.md