# Sandboxes Overview

> Create isolated Linux sandboxes for agent work, code execution, file operations, and short-lived services.

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](https://docs.watasu.io/apps/deploy.md) instead.

The fastest way to try a sandbox is [SSH](https://docs.watasu.io/sandboxes/ssh.md): `ssh base@box.watasu.io` creates one and opens a shell inside it — no SDK or setup required. The rest of this page covers the HTTP API that SDKs and automations use.

## 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:

```bash
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`. Basic teams use that baseline. Pro and Enterprise teams can override CPU or memory at start within their active team plan limits. Runtime billing is based on the vCPU and memory actually requested for the sandbox.

```bash
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
* active team sandbox plan and the public plan catalog
* allowed CPU values
* memory minimum, maximum, and increment
* plan-managed root disk size
* 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` accepts a template slug such as `base` and resolves to the latest runnable version. Use `template: "base:<version-or-id>"` only when you need an exact pinned build. If `template` does not match a template, Watasu treats it as a snapshot id visible to the selected team; you can also pass `snapshot_id` explicitly.

```bash
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": "watasu",
    "template": "base",
    "timeout": 3600,
    "lifecycle": {
      "on_timeout": "pause",
      "auto_resume": false
    },
    "metadata": {
      "job": "support-ticket-1837"
    },
    "envs": {
      "OPENAI_API_KEY": "..."
    },
    "volume_mounts": {
      "/workspace/cache": "cache"
    }
  }'
```

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

```json
{
  "template": "base:2026-06-14",
  "timeout": 3600
}
```

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

```json
{
  "template": "456",
  "timeout": 3600
}
```

Root disk size is plan-managed: Basic teams get a 10 GiB root disk and Pro teams get 20 GiB. If `team` is omitted, Watasu uses your personal team. `envs` 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:

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

Detached volumes support directory and file operations:

```bash
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
while preserving the machine — the sandbox's memory and running processes are
saved alongside the retained disk, and a later resume continues them in place. `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.

```bash
curl --get https://api.watasu.io/v1/sandboxes \
  -H "Authorization: Bearer $WATASU_API_KEY" \
  --data-urlencode "team=watasu" \
  --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.

```bash
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 was paused, Watasu wakes the machine exactly where it stopped: running processes, memory state, and open handles all continue — resume is a continuation, not a restart. (The clock jumps forward, as after any suspend; long-lived TLS sessions and timers inside the sandbox should tolerate that.) When a machine-state image is not available — for example after a platform upgrade, or for sandboxes with attached volumes — resume falls back to restarting the retained disk with the same sandbox id: your files are always intact, and processes start fresh. If a previous pause/stop request is still finishing, resume waits briefly and then continues the same sandbox once it is ready. `connect` remains available as an alias.

```bash
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:

```json
{
  "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.

```bash
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:

```bash
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](https://docs.watasu.io/sandboxes/billing.md).

## Related pages

* [SSH](https://docs.watasu.io/sandboxes/ssh.md)
* [Templates](https://docs.watasu.io/sandboxes/templates.md)
* [Files and Processes](https://docs.watasu.io/sandboxes/files-and-commands.md)
* [Checkpoints](https://docs.watasu.io/sandboxes/checkpoints.md)
* [Networking and Ports](https://docs.watasu.io/sandboxes/networking.md)
* [Sandbox Billing](https://docs.watasu.io/sandboxes/billing.md)

[View this page on the web](https://docs.watasu.io/sandboxes/overview/)