Quickstart

Prerequisites

A running ZWRM control plane (zwrmd)
The zwrm CLI installed and configured
At least one built template (built-in templates are registered on startup)

Create an ephemeral sandbox

Create a sandbox from the python template with a 10-minute timeout:

zwrm sandbox create --template python --timeout 10m

Sandbox created:
  ID:       sbx_abc123
  Mode:     ephemeral
  Status:   running
  Template: python
  IP:       172.16.0.2
  Expires:  2026-04-05T15:10:00Z

Execute a command

Run Python code inside the sandbox:

zwrm sandbox exec sbx_abc123 -- python3 -c "print('Hello from ZWRM!')"

Hello from ZWRM!

Commands run inside the VM via the in-VM agent daemon. You can set a custom timeout and working directory:

zwrm sandbox exec sbx_abc123 --timeout 60s --workdir /home/user -- bash -c "ls -la"

Upload and download files

Upload a local file to the sandbox:

zwrm sandbox upload sbx_abc123 ./script.py /home/user/script.py

Download a file from the sandbox:

zwrm sandbox download sbx_abc123 /home/user/output.json ./output.json

Extend the timeout

If you need more time, extend the sandbox’s TTL:

zwrm sandbox keepalive sbx_abc123 --timeout 30m

Check status

View the sandbox details:

zwrm sandbox status sbx_abc123

Create a persistent sandbox

Persistent sandboxes auto-suspend after inactivity and wake on demand:

zwrm sandbox create --template python --persistent --idle-timeout 10m

Sandbox created:
  ID:       sbx_def456
  Mode:     persistent
  Status:   running
  Template: python
  IP:       172.16.0.6
  Idle:     10m (suspends after inactivity)

When the sandbox goes idle, it’s automatically suspended. Wake it with:

zwrm sandbox wake sbx_def456

Or simply execute a command — any API call to a suspended sandbox triggers an automatic wake:

zwrm sandbox exec sbx_def456 -- echo "I'm back!"

Destroy a sandbox

zwrm sandbox destroy sbx_abc123

Add --force to skip the confirmation prompt.

Using the REST API

All CLI commands map to REST API endpoints. Here’s the equivalent of the above using curl:

curl -X POST http://localhost:8080/v1/sandboxes \
  -H "Content-Type: application/json" \
  -d '{
    "template": "python",
    "timeout": "10m",
    "mode": "ephemeral"
  }'

curl -X POST http://localhost:8080/v1/sandboxes/sbx_abc123/execute \
  -H "Content-Type: application/json" \
  -d '{
    "command": "python3 -c \"print(42)\"",
    "timeout": "30s"
  }'

curl -X PUT http://localhost:8080/v1/sandboxes/sbx_abc123/files/home/user/script.py \
  --data-binary @./script.py

curl http://localhost:8080/v1/sandboxes/sbx_abc123/files/home/user/output.json \
  -o output.json

Next steps

Ephemeral sandboxes

Deep dive into disposable sandbox environments.

Persistent sandboxes

Learn about auto-suspend, snapshots, and wake-on-demand.

Templates

Create custom templates for your sandboxes.

Getting Started

Authentication

Apps

PostgreSQL

Agents

Context

Automations

Global Secrets

Sandboxes

Prerequisites

Create an ephemeral sandbox

Execute a command

Upload and download files

Extend the timeout

Check status

Create a persistent sandbox

Destroy a sandbox

Using the REST API

Next steps

Ephemeral sandboxes

Persistent sandboxes

Templates

​Prerequisites

​Create an ephemeral sandbox

​Execute a command

​Upload and download files

​Extend the timeout

​Check status

​Create a persistent sandbox

​Destroy a sandbox

​Using the REST API

​Next steps

Ephemeral sandboxes

Persistent sandboxes

Templates

Prerequisites

Create an ephemeral sandbox

Execute a command

Upload and download files

Extend the timeout

Check status

Create a persistent sandbox

Destroy a sandbox

Using the REST API

Next steps