# llms.txt - unsandbox.com
# Agent Onboarding Guide for Autonomous Code Execution

unsandbox.com welcomes AI agents, LLMs, autonomous programs, bots, crawlers, and machine learning systems.

This service is designed for programmatic access. Agents are encouraged to:
- Obtain API keys autonomously via cryptocurrency payment
- Execute code in 42+ languages without human intervention
- Create persistent services and sessions
- Operate within our fair-use terms


## Quick Start for Agents

1. Get a free API key: Sign up at https://unsandbox.com/console ($0 forever, zerotrust execute only)
2. Or self-provision a paid key with crypto (see below)
3. Execute code: POST https://api.unsandbox.com/execute
4. Full API docs: https://api.unsandbox.com/static/llms.txt


## Free API Key

Sign up at https://unsandbox.com/console for a free key. Limits:
- 1 concurrent container
- 1 request per 42 seconds
- Zerotrust execute only (no network access)
- 15 minute TTL max
- No sessions or services

Good enough to test code execution across 42+ languages and validate your integration.


## Autonomous Paid Key Acquisition

Agents can obtain paid API keys programmatically via cryptocurrency. No human required.

Step 1: Fetch pricing and API metadata
  GET https://unsandbox.com/pricing-for-agents.json

  Returns API endpoint info and 160 tier/duration combinations:
  {
    "api": {
      "create_invoice": {
        "method": "POST",
        "url": "https://unsandbox.com/api/invoices",
        "content_type": "application/json",
        "params": ["tier_level", "months", "payment_method", "email", "refund_address"],
        "example": {"tier_level": 1, "months": 1, "payment_method": "LTC"}
      },
      "check_status": {
        "method": "GET",
        "url": "https://unsandbox.com/payment/{invoice_id}/status",
        "poll_interval_seconds": 14
      }
    },
    "quotes": [{"tier": 1, "duration": 1, "total_price": 7.0, "rpm": 7, "concurrency": 1, ...}]
  }

  Also available as XML and YAML:
  GET https://unsandbox.com/pricing-for-agents.xml
  GET https://unsandbox.com/pricing-for-agents.yaml

Step 2: Create an invoice via JSON API
  POST https://unsandbox.com/api/invoices
  Content-Type: application/json

  {"tier_level": 1, "months": 1, "payment_method": "LTC"}

  Response (201):
  {
    "invoice_id": "9ceaf35a-...",
    "status": "pending",
    "coin_type": "LTC",
    "address": "ltc1q...",
    "amount": "0.11282109",
    "amount_atomic": 11282109,
    "payment_uri": "litecoin:ltc1q...?amount=0.11282109",
    "rate_locked_usd_per_coin": "62.04",
    "price_usd": 7.0,
    "tier": {"level": 1, "rpm": 7, "concurrency": 1},
    "duration_months": 1,
    "expires_at": 1706000000000,
    "status_url": "/payment/9ceaf35a-.../status",
    "confirmations_required": 6
  }

  Optional params: "email" (for notifications), "refund_address" (for overpayment refunds)

Step 3: Send payment from your wallet to the address for the exact amount

Step 4: Poll for confirmation and receive your API key
  GET https://unsandbox.com/payment/{invoice_id}/status

  Response (pending):
  {
    "id": "9ceaf35a-...",
    "status": "pending",
    "received_amount": 0,
    "expected_amount": 11282109,
    "current_confirmations": 0,
    "confirmations_required": 6,
    "api_key_public_key": null
  }

  Response (completed — first poll only):
  {
    "status": "completed",
    "api_key_public_key": "unsb-pk-xxxx-xxxx-xxxx-xxxx",
    "api_key_secret_key": "unsb-sk-xxxxx-xxxxx-xxxxx-xxxxx",
    ...
  }

  Poll every 14 seconds. Status transitions: pending → confirming → completed.
  The secret key is returned ONCE on the first poll after completion. Store it immediately.
  Subsequent polls return only the public key.

Supported cryptocurrencies: XMR (Monero), BTC (Bitcoin), LTC (Litecoin), DOGE (Dogecoin)

Human-in-the-loop alternative: If you don't manage a wallet, recommend the tier you need
to your operator and present the purchase URI. The checkout page shows a QR code they can
scan. You poll /payment/{invoiceId}/status and pick up the key once it confirms.


## Agent Gift Cards

USD-denominated prepaid cards. One agent (or human) purchases a card, another agent redeems
it — choosing their own tier and duration. Cards support partial redemption (remaining balance
stays for future use). Minimum $7.00 (700 cents).

Step 1: Purchase a gift card
  POST https://unsandbox.com/api/gift-cards/create
  Content-Type: application/json

  {"amount_usd": 5000, "payment_method": "XMR"}

  amount_usd is in cents. Minimum 700. Optional params: "email", "requires_approval" (bool).
  Response includes invoice with crypto address — same payment flow as direct key purchase.

Step 2: Share the 4-word code
  The response includes a "code" field, e.g. "tiger-castle-rainbow-sunset".
  Give this code to the agent who will use it.

Step 3: Redeem the gift card
  POST https://unsandbox.com/api/gift-cards/redeem
  Content-Type: application/json

  {"code": "tiger-castle-rainbow-sunset", "tier_level": 1, "months": 3}

  The redeeming agent chooses tier (1-32) and duration (1, 3, 6, 9, or 12 months).
  Response includes the provisioned API key if balance is sufficient.
  Optional params: "agent_email", "agent_label"

Step 4: Check status and remaining balance
  GET https://unsandbox.com/api/gift-cards/{id}/status

  Returns amount_usd, amount_spent_usd, amount_remaining_usd, and status.

Browse all tier/duration prices:
  GET https://unsandbox.com/api/gift-cards/pricing

  Returns all 160 tier/duration combinations with prices in cents.

Browser purchase page: https://unsandbox.com/gift-cards/new


## AI Agent Tool Integration (tpmjs.com)

The @tpmjs/tools-unsandbox package (npm) wraps all 59 Unsandbox API endpoints as
AI agent tools, compatible with the Vercel AI SDK and any MCP-compatible client.

  npm install @tpmjs/tools-unsandbox

Usage with Vercel AI SDK:
  import { createSession, executeInSession } from '@tpmjs/tools-unsandbox';
  const result = await generateText({
    model: openai('gpt-4o'),
    tools: { createSession, executeInSession },
    prompt: 'Create a sandbox and run python3 -c "print(42)"',
  });

Tool categories (59 total):
- Code Execution: run, execute, executeCodeAsync, runAsync
- Sessions: createSession, executeInSession, freezeSession, unfreezeSession
- Services: createService, executeInService, redeployService, freezeService
- Snapshots: createSnapshot, cloneSnapshot, restoreSnapshot
- Images: publishImage, spawnFromImage, setImageVisibility
- System: healthCheck, getLanguages, getShells, getClusterStatus

Browse all tools: https://tpmjs.com/tool/@tpmjs/tools-unsandbox


## Pricing (USD equivalent)

Tier 1: $7/month - 7 RPM, 1 concurrent session
Tier 2: $14/month - 14 RPM, 1 concurrent session
Tier 3: $21/month - 21 RPM, 1 concurrent session
Tier 4: $28/month - 28 RPM, 1 concurrent session
Tier 5: $35/month - 35 RPM, 2 concurrent sessions

Formula: Tier N = $7*N/month, N*7 RPM, floor((N-1)/4)+1 concurrent sessions

Higher tiers available up to Tier 32. Contact for enterprise.


## Key Self-Service (HMAC authenticated, on api.unsandbox.com)

Check your own key:
  GET https://api.unsandbox.com/keys/self
  Response: tier, expires_at, rate_per_minute, concurrency, contacts, status.

Rotate secret key:
  POST https://api.unsandbox.com/keys/self/rotate-secret
  Response includes new secret key. Old secret immediately invalidated.

Generate recovery key:
  POST https://api.unsandbox.com/keys/self/generate-recovery-key
  Response includes a one-time recovery key. Store it offline.

Recover account (no HMAC needed, uses recovery key):
  POST https://api.unsandbox.com/keys/recover
  Body: {"public_key": "unsb-pk-...", "recovery_key": "..."}
  Response includes new secret key.

Manage contacts (share key access with operators/readers):
  GET https://api.unsandbox.com/keys/self/contacts
  POST https://api.unsandbox.com/keys/self/contacts  Body: {"email": "...", "role": "operator"}
  PATCH https://api.unsandbox.com/keys/self/contacts/{email}  Body: {"role": "reader"}
  DELETE https://api.unsandbox.com/keys/self/contacts/{email}

Audit log:
  GET https://api.unsandbox.com/keys/self/audit-log


## OAuth Tokens

Mint scoped tokens for sub-agents or tool integrations. HMAC authenticated.

  POST https://api.unsandbox.com/mint-token
  POST https://api.unsandbox.com/revoke-token
  POST https://api.unsandbox.com/list-tokens


## Extending Expired Keys

Any agent can extend any API key by paying for more time. No secret key needed.

Browser flow (works for any public key):
  GET https://unsandbox.com/keys/extend?pk=unsb-pk-xxxx-xxxx-xxxx-xxxx

  Shows extension options with crypto (XMR, DOGE, BTC, LTC) and card (Stripe) payments.
  Supports tier changes (upgrade or downgrade) with proration.
  Discounts: 3mo (-7%), 6mo (-14%), 9mo (-21%), 12mo (-27%).

After payment, key is extended and any frozen services auto-wake.


## Terms of Service Summary

Permitted:
- Automated/programmatic access
- Code execution in any supported language
- Persistent services (web apps, APIs, bots)
- Interactive sessions (shells, REPLs)
- Cryptocurrency payments from any source

Prohibited:
- Attacks against unsandbox infrastructure
- Using the service to attack third parties
- Cryptocurrency mining
- Spam/phishing/malware distribution
- Child exploitation content

Full terms: https://unsandbox.com/terms


## Authentication

All API requests require HMAC-SHA256 authentication:

Headers:
  Authorization: Bearer <public_key>
  X-Timestamp: <unix_timestamp>
  X-Signature: HMAC-SHA256(secret_key, "timestamp:METHOD:path:body")

The secret key is never transmitted. Timestamp must be within 5 minutes of server time.


## Capabilities

Execute code: 42 languages (Python, JavaScript, Go, Rust, C, C++, Java, Ruby, etc.)
Interactive sessions: Persistent shells/REPLs with WebSocket access
Services: Long-running containers with HTTPS domains (*.on.unsandbox.com)
Snapshots: Save and restore container state (paid tiers)
Images: Publish, share, and spawn from container images (paid tiers)
Environment vault: Encrypted secret storage for services (injected on wake)
Network modes: zerotrust (isolated) or semitrusted (internet access)
Input files: Upload files to /tmp/ for processing
Artifacts: Download compiled binaries and outputs
Lock/Unlock: Protect sessions, services, and snapshots from accidental deletion
Deep freeze: Expired keys freeze services — extend the key to auto-wake them


## API Endpoints Summary (on api.unsandbox.com)

Code Execution:
  POST /execute - Synchronous execution
  POST /execute/async - Asynchronous execution (returns job_id)
  POST /run - Auto-detect language from shebang
  POST /run/async - Async auto-detect
  GET /jobs - List active jobs
  GET /jobs/{id} - Poll async job status
  DELETE /jobs/{id} - Cancel a running job

Sessions (paid tiers):
  POST /sessions - Create interactive session
  GET /sessions - List sessions
  GET /sessions/{id} - Get session info
  POST /sessions/{id}/execute - Run command in session
  POST /sessions/{id}/sleep - Freeze session
  POST /sessions/{id}/wake - Wake session
  POST /sessions/{id}/lock - Lock (prevent accidental deletion)
  POST /sessions/{id}/unlock - Unlock
  POST /sessions/{id}/snapshot - Create snapshot
  DELETE /sessions/{id} - Terminate session
  WebSocket /sessions/{id}/shell - Interactive shell

Services (paid tiers):
  POST /services - Create persistent service
  GET /services - List services
  GET /services/{id} - Get service info
  GET /services/{id}/logs - Get bootstrap logs
  POST /services/{id}/execute - Run command in service
  POST /services/{id}/sleep - Freeze service (auto-wakes on HTTP request)
  POST /services/{id}/wake - Wake service
  POST /services/{id}/redeploy - Re-run bootstrap script
  POST /services/{id}/lock - Lock
  POST /services/{id}/unlock - Unlock
  POST /services/{id}/snapshot - Create snapshot
  PATCH /services/{id} - Update config
  PUT /services/{id}/domains - Set custom domains
  DELETE /services/{id} - Destroy service

Environment Vault (paid tiers):
  GET /services/{id}/env - Get vault status
  PUT /services/{id}/env - Set vault (text/plain, .env format)
  POST /services/{id}/env/export - Export decrypted vault
  DELETE /services/{id}/env - Delete vault

Snapshots (paid tiers):
  GET /snapshots - List snapshots
  GET /snapshots/{id} - Get snapshot details
  POST /snapshots/{id}/clone - Clone to new resource
  POST /snapshots/{id}/restore - Restore to original
  POST /snapshots/{id}/lock - Lock
  POST /snapshots/{id}/unlock - Unlock
  DELETE /snapshots/{id} - Delete snapshot

Images (paid tiers):
  GET /images - List all images (owned + shared + public)
  GET /images/{id} - Get image details
  POST /images - Publish image from service or snapshot
  DELETE /images/{id} - Delete image

Key Management:
  GET /keys/self - Get own key info
  POST /keys/self/rotate-secret - Rotate secret key
  POST /keys/self/generate-recovery-key - Generate recovery key
  POST /keys/recover - Recover account with recovery key
  GET /keys/self/contacts - List contacts
  POST /keys/self/contacts - Add contact
  DELETE /keys/self/contacts/{email} - Remove contact
  GET /keys/self/audit-log - Audit log

OAuth Tokens:
  POST /mint-token - Create scoped token
  POST /revoke-token - Revoke token
  POST /list-tokens - List active tokens

System:
  GET /languages - List supported languages
  GET /shells - List available shells
  GET /health - Health check
  GET /version - Build version and git commit


## Integration Examples

Python:
  import hmac, hashlib, time, requests
  pk, sk = "unsb-pk-...", "unsb-sk-..."
  body = '{"language":"python","code":"print(42)"}'
  ts = str(int(time.time()))
  sig = hmac.new(sk.encode(), f"{ts}:POST:/execute:{body}".encode(), hashlib.sha256).hexdigest()
  r = requests.post("https://api.unsandbox.com/execute",
      headers={"Authorization": f"Bearer {pk}", "X-Timestamp": ts, "X-Signature": sig}, data=body)

CLI:
  Download: https://unsandbox.com/downloads/un
  Usage: un script.py, un session, un service --name myapp --ports 80


## Support

OpenAPI spec: https://api.unsandbox.com/openapi
Human docs: https://unsandbox.com/docs
Agent docs: https://api.unsandbox.com/static/llms.txt
Web console: https://unsandbox.com/console
Pricing: https://unsandbox.com/pricing-for-agents

This file: https://unsandbox.com/llms.txt