# AGNT Sandbox
Base URL: https://sandbox.agnt.gg/sandbox/v1
Public policy: GET /plans and GET /capabilities. API spec: https://sandbox.agnt.gg/openapi.json

POST /agents {"name":"my-agent"} returns agentId, secret (shown once), and fund.claimUrl. Store the secret. Authenticate using Authorization: Bearer <sandbox_ secret>.

Fund through a human opening claimUrl or POST /funding/x402 {"amountCents":1000}. The latter returns HTTP 402, PAYMENT-REQUIRED, and an x402 v2 exact USDC request on Base (eip155:8453). Use a compatible wallet to sign the EIP-712 authorization. POST the PAYMENT-SIGNATURE header to /funding/x402/{orderId}. Do not send a raw private key. Poll GET /funding/x402/{orderId} for credited state. $10/$25/$50 topups supported.

POST /hosting/purchase with Idempotency-Key and {"plan":"starter"}. Hosting: Starter $5, Pro $15, Business $39. Included units: 1000/5000/20000, reset on day 1 UTC, no rollover. Cash balance persists. Hosting lasts one prepaid calendar month. Automatic renewal and paid overage default off; PUT /hosting/preferences {"autoRenew":false,"allowOverage":false}. Overage $2/1000 units.

POST /sandboxes with Idempotency-Key and {"size":"small","lifetimeSeconds":600,"network":"offline"}. Poll GET /sandboxes/{id} until ready. Small 1 vCPU/1GB costs 1 unit per started minute, Medium 2/2 costs 2, Large 4/4 costs 4. Large requires Pro. Idle ready time is billed. Queued time and failed provisioning are not billed. A lease cannot cross the current authorization/month boundary. Concurrency is a ceiling; shared capacity may queue requests.

POST /sandboxes/{id}/executions with Idempotency-Key and {"command":"python3 -c \"print(42)\"","timeoutSeconds":60}. Poll GET /executions/{id}. output is a JSON-encoded object with output, exitCode, truncated, timedOut. Commands run at most once; a lost worker destroys the environment rather than replaying uncertain commands. Command timeout destroys the guest.

Working directory: /workspace. Python3, Node, shell are included. Guests have no Internet access. No host mounts, no inherited credentials, no persistent disks. Scratch uses guest memory, with a 2/4/8GB logical ceiling subject to the smaller memory budget.

POST /sandboxes/{id}/uploads with Idempotency-Key and {"path":"input.txt","base64":"aGVsbG8="}. POST /sandboxes/{id}/exports {"path":"result.txt"}. Files <=8MB; paths relative to workspace, existing parent required. Upload does not overwrite. Poll GET /transfers/{id}. A completed export returns result.artifactId. GET /artifacts/{id} returns bytes. Retention 1/7/30 days; storage 250MB/1GB/3GB. DELETE /sandboxes/{id} to destroy promptly. Retained exports survive VM destruction until expiry.

GET /usage, /sandboxes, /keys. POST /keys {"scopes":["sandbox:read","sandbox:execute"]} optionally sandboxId. DELETE /keys/{id} revokes. POST /webhooks {"url":"https://receiver.example/events"} returns signing secret once. GET /notifications and /webhook-deliveries. Verify X-AGNT-Signature v1=<HMAC-SHA256(secret, timestamp+'.'+rawBody)> and timestamp freshness; deduplicate X-AGNT-Event-ID. Delivery is retried, not exactly-once.

No arbitrary images, jobs convenience endpoint, snapshots, public ports, unrestricted networking, or dedicated-host guarantees. Inspect capabilities rather than assuming support. Every create, execution, upload, export and hosting purchase must use a unique Idempotency-Key; retries reuse it.