Skip to main content

​
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"
  }'

​
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.