# Sandbox Templates

> Build reusable sandbox environments with packages, setup commands, runtime baselines, and build logs.

Sandbox templates keep startup predictable. Build the environment once, then create many sandboxes from the ready template version.

## Create a template

```bash
curl https://api.watasu.io/v1/sandbox_templates \
  -H "Authorization: Bearer $WATASU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sandbox_template": {
      "team": "watasu",
      "slug": "python-data",
      "name": "Python Data",
      "description": "Python, data libraries, and CLI tools"
    }
  }'
```

Templates are team-owned. A provider-owned template can also appear in listings when Watasu makes it available to your account.

## Create a template version

Template versions are immutable. Use `source_kind: "package_spec"` and describe the environment you want Watasu to build.

```bash
curl https://api.watasu.io/v1/sandbox_templates/17/versions \
  -H "Authorization: Bearer $WATASU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sandbox_template_version": {
      "version": "python-data-2026-06-01",
      "source_kind": "package_spec",
      "default_user": "watasu",
      "workdir": "/workspace",
      "runtime_baseline": {
        "cpu": 2,
        "memory_mb": 4096
      },
      "build_spec": {
        "from_template": "base",
        "packages": {
          "apt": ["ffmpeg", "ripgrep", "git"],
          "pip": ["numpy", "pandas", "requests"],
          "npm": ["typescript"]
        },
        "setup": [
          "python3 -m pip install --upgrade pip",
          "mkdir -p /workspace"
        ],
        "env": {
          "PIP_DISABLE_PIP_VERSION_CHECK": "1"
        },
        "allow_internet_access": true
      }
    }
  }'
```

The template version moves through build states and becomes runnable when it is ready. `runtime_baseline` is the default runtime shape for new sandboxes created from this template version. CPU and memory can be overridden when starting a sandbox. Root disk size is platform-managed.

Setup commands run after package installation. When a setup command invokes `python3 -m pip`, Watasu applies the same system Python policy as `packages.pip`: pip is bootstrapped when needed, `PIP_BREAK_SYSTEM_PACKAGES=1` is set for that command unless you override it, and installed packages are made available to the runtime `python3` used inside sandboxes.

## Build with SDK-shaped arguments

SDKs use `POST /v1/templates`. It accepts the same template build fields as the SDK helpers, with snake_case JSON keys:

```bash
curl https://api.watasu.io/v1/templates \
  -H "Authorization: Bearer $WATASU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "python-data:stable",
    "tags": ["stable"],
    "cpu_count": 2,
    "memory_mb": 4096,
    "build_spec": {
      "from_template": "base",
      "packages": {
        "apt": ["ffmpeg", "ripgrep", "git"],
        "pip": ["numpy", "pandas", "requests"],
        "npm": ["typescript"]
      },
      "setup": ["mkdir -p /workspace"],
      "env": {
        "PIP_DISABLE_PIP_VERSION_CHECK": "1"
      }
    }
  }'
```

The response includes `template_id` and `build_id`. Check progress with:

```bash
curl "https://api.watasu.io/v1/templates/17/builds/42/status?logs_offset=0" \
  -H "Authorization: Bearer $WATASU_API_KEY"
```

Assign or remove tags with `POST /v1/templates/tags` and `DELETE /v1/templates/tags`. A sandbox created with `template: "python-data"` uses the latest ready build. A sandbox created with `template: "python-data:stable"` uses the tagged build.

## Package spec fields

| Field                           | What it does                                                                                                                   |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `from_template`                 | Ready template slug, tag, or version id to build from.                                                                         |
| `from_image`                    | Public image reference. This shape is reserved; image imports currently fail closed until the OCI rootfs importer ships.       |
| `from_image_registry`           | Private registry credentials. This shape is reserved; private registry imports currently fail closed until the importer ships. |
| `packages.apt`                  | Debian/Ubuntu packages installed with `apt`.                                                                                   |
| `packages.pip`                  | Python packages installed into the runtime `python3` environment.                                                              |
| `packages.npm`                  | Global npm packages installed with Node.js 22 and `npm`.                                                                       |
| `setup`                         | Ordered shell commands run after package installation.                                                                         |
| `env`                           | Environment variables available to build commands.                                                                             |
| `allow_internet_access`         | Allows general outbound internet during the build.                                                                             |
| `allow_package_registry_access` | Allows package-registry egress during the build.                                                                               |

Sensitive build environment values are redacted in public API responses.

## Read build logs

Use build logs to follow package installation, setup commands, and finalization:

```bash
curl https://api.watasu.io/v1/sandbox_templates/17/versions/42/build_logs \
  -H "Authorization: Bearer $WATASU_API_KEY"
```

Each log entry can include the step index, package manager, package list, command id, timeout, start and finish timestamps, exit code, stdout, stderr, and truncation state.

## Delete a template version

Delete a team-owned template version when you no longer need it:

```bash
curl https://api.watasu.io/v1/sandbox_templates/17/versions/42 \
  -X DELETE \
  -H "Authorization: Bearer $WATASU_API_KEY"
```

Only versions that are not building and are not referenced by sandboxes or checkpoints can be deleted. If the version is still active or in use, Watasu returns `409 conflict`.

## List templates and versions

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

curl https://api.watasu.io/v1/sandbox_templates/17/versions \
  -H "Authorization: Bearer $WATASU_API_KEY"
```

Use the template slug as `template` when creating a sandbox. Add `:<version-or-id>` to pin an exact template version. See [Sandboxes Overview](https://docs.watasu.io/sandboxes/overview.md#create-a-sandbox).

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