Sandbox Templates

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

Create a template

curl https://api.watasu.io/v1/sandbox_templates \
  -H "Authorization: Bearer $WATASU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sandbox_template": {
      "team": "acme",
      "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.

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:

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:

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_id: "python-data" uses the latest ready build. A sandbox created with template_id: "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:

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:

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

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_id when creating a sandbox. Add :<version-or-id> to pin an exact template version. See Sandboxes Overview.