Sandboxes Overview

Watasu sandboxes are isolated Linux environments created from reusable templates. They are designed for agent workflows: run code, write files, stream processes, expose a preview port, take a checkpoint, and clean up when the work is done.

When to use a sandbox

Use a sandbox when you need:

a short-lived Linux workspace for an AI agent or automation task
code execution without deploying a full Watasu app
a prepared environment with known packages and setup commands
file upload/download and command execution through an API
a temporary HTTP preview URL for something running inside the sandbox
a restorable disk checkpoint while a task is in progress

For long-running web services, workers, private TCP services, and WebRTC processes, use Apps instead.

Core objects

Object	What it represents
Sandbox template	A named environment definition owned by your team.
Sandbox template version	An immutable, built template artifact that new sandboxes can start from.
Sandbox instance	One running or stopped sandbox created from a template version.
Sandbox checkpoint	A named disk checkpoint you can restore into a new sandbox.

API conventions

Sandbox APIs live under https://api.watasu.io/v1. Use a Watasu API key as a bearer token:

export WATASU_API_KEY="..."

curl https://api.watasu.io/v1/sandbox_limits \
  -H "Authorization: Bearer $WATASU_API_KEY"

Create API keys from the dashboard. Use read-capable keys for listing and inspecting resources, and write-capable keys for creating templates, sandboxes, data-plane file/process sessions, and checkpoints.

Mutating control-plane sandbox endpoints accept Idempotency-Key. Use it for retries so a network timeout does not accidentally create the same sandbox or checkpoint twice.

Check resource limits

Each template version has a runtime_baseline. Sandbox creation uses that baseline unless you override CPU or memory at start. Runtime billing is based on the vCPU and memory actually requested for the sandbox.

curl https://api.watasu.io/v1/sandbox_limits \
  -H "Authorization: Bearer $WATASU_API_KEY"

The response includes:

fallback cpu and memory_mb values for new template baselines
allowed CPU values
memory minimum, maximum, and increment
maximum timeout
runtime and storage prices

The response also includes quota for the selected team. Use it to show the team’s current sandbox limits, active usage, and the reservation shape that would be checked on create.

Create a sandbox

Create a sandbox from a ready template or snapshot. template_id accepts a template slug such as base and resolves to the latest runnable version. Use template_id: "base:<version-or-id>" only when you need an exact pinned build. If template_id does not match a template, Watasu treats it as a snapshot id visible to the selected team; you can also pass snapshot_id explicitly.

curl https://api.watasu.io/v1/sandboxes \
  -H "Authorization: Bearer $WATASU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sandbox-create-001" \
  -d '{
    "team": "acme",
    "template_id": "base",
    "timeout": 3600,
    "lifecycle": {
      "on_timeout": "pause",
      "auto_resume": false
    },
    "metadata": {
      "job": "support-ticket-1837"
    },
    "env_vars": {
      "OPENAI_API_KEY": "..."
    },
    "volume_mounts": {
      "/workspace/cache": "cache"
    }
  }'

Pin an exact build when reproducibility matters more than receiving the newest platform template:

{
  "template_id": "base:2026-06-14",
  "timeout": 3600
}

Create from a snapshot when you want to continue from a saved sandbox disk state:

{
  "template_id": "456",
  "timeout": 3600
}

Root disk size and template resources are platform-managed. If team is omitted, Watasu uses your personal team. env_vars are encrypted at rest and sent to the sandbox runtime, but they are not echoed in sandbox list/show responses. volume_mounts mounts named persistent volumes at absolute guest paths; each volume uses the platform-managed baseline size and can be reused by later sandboxes that mount the same name for the same team. The response includes the sandbox id, state, template, timeout, deadline, lifecycle policy, volume mounts, CPU/memory allocation, metadata, and data-plane URL. Sandbox metadata is returned as string keys and string values; non-string values sent on create or update are stringified.

Persistent volumes

Create and manage named team-scoped volumes before mounting them into a sandbox:

curl https://api.watasu.io/v1/volumes \
  -H "Authorization: Bearer $WATASU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "team": "acme",
    "name": "cache"
  }'

Detached volumes support directory and file operations:

curl https://api.watasu.io/v1/volumes/123/files \
  -X PUT \
  -H "Authorization: Bearer $WATASU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/workspace/status.txt",
    "content_b64": "cmVhZHkK",
    "mode": "0644"
  }'

Use GET /v1/volumes, GET /v1/volumes/:id, and DELETE /v1/volumes/:id for volume lifecycle. Use /files, /directories, and /path under /v1/volumes/:id for detached content operations. Watasu refuses destructive or write operations while the volume is attached to a live sandbox, because the same ext4 image must not be modified from the host while the guest has it mounted.

The default lifecycle policy is { "on_timeout": "kill", "auto_resume": false }. Use { "on_timeout": "pause" } when the timeout should release runtime capacity but keep the retained disk. auto_resume is only valid with pause; when true, a later data-plane file, process, or directory request can resume the paused sandbox automatically. You can also send auto_pause: true as a shorthand for lifecycle.on_timeout: "pause".

If the request would exceed the team’s sandbox quota, Watasu returns 422 Unprocessable Entity with error: "sandbox_quota_exceeded" and the same quota snapshot shape returned by /v1/sandbox_limits.

List sandboxes

List sandboxes visible to your API key with optional team, metadata, state, and pagination filters. The running state alias includes live-ish runtime states such as creating, ready, restoring, checkpointing, and stopping. The paused alias matches stopped sandboxes.

curl --get https://api.watasu.io/v1/sandboxes \
  -H "Authorization: Bearer $WATASU_API_KEY" \
  --data-urlencode "team=acme" \
  --data-urlencode "limit=20" \
  --data-urlencode "query[metadata][job]=support-ticket-1837" \
  --data-urlencode "query[state][]=running"

When more rows are available, the response includes next_token. Pass it back as next_token to fetch the next page with the same filters.

curl --get https://api.watasu.io/v1/sandboxes \
  -H "Authorization: Bearer $WATASU_API_KEY" \
  --data-urlencode "next_token=123" \
  --data-urlencode "limit=20"

Resume or connect to a sandbox

Resume refreshes the sandbox deadline and returns a short-lived data-plane session token. If the sandbox is stopped, Watasu restarts the retained disk with the same sandbox id before returning the session. If a previous pause/stop request is still finishing, resume waits briefly and then starts the same sandbox once the retained disk is ready. connect remains available as an alias.

curl https://api.watasu.io/v1/sandboxes/123/resume \
  -X POST \
  -H "Authorization: Bearer $WATASU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "timeout": 3600 }'

The response includes:

{
  "session": {
    "data_plane_url": "https://<route-token>.sandbox.watasuhost.com",
    "access_token": "...",
    "expires_at": "2026-06-01T12:00:00Z"
  }
}

Use the access_token for data-plane file, directory, and streaming process operations.

Pause, stop, or destroy

Pause a sandbox when you want to release runtime capacity but keep the retained disk. stop remains available as an alias.

curl https://api.watasu.io/v1/sandboxes/123/pause \
  -X POST \
  -H "Authorization: Bearer $WATASU_API_KEY"

Destroy a sandbox when you are finished with it:

curl https://api.watasu.io/v1/sandboxes/123 \
  -X DELETE \
  -H "Authorization: Bearer $WATASU_API_KEY"

Stopped retained disks and checkpoints are billed as storage until they are removed by lifecycle cleanup or replaced by a restored running sandbox. See Sandbox Billing.