Ephemeral sandboxes are short-lived, disposable environments that are automatically destroyed when their timeout expires. They’re designed for one-off tasks like code execution, CI/CD jobs, testing, and AI agent tool calls.
Lifecycle
- Create with a timeout (default: 5 minutes, max: 24 hours)
- Use — execute commands, upload/download files
- Extend — call keepalive to push back the expiry
- Destroy — happens automatically at expiry, or manually
A background reaper loop runs every 10 seconds and destroys any ephemeral sandboxes past their expires_at timestamp.
Creating an ephemeral sandbox
zwrm sandbox create --template python --timeout 10m
--template (required) — Template name or ID--timeout — Duration until auto-destroy (default: 5m, max: 24h)--size — VM preset (default: shared-cpu-1x)--env KEY=VALUE — Environment variables (repeatable)--egress-mode — Outbound firewall mode: allow_all or deny_all--egress-allow-cidr CIDR — Allow outbound to this CIDR (repeatable; implies deny_all)--egress-deny-cidr CIDR — Explicitly deny outbound to this CIDR (repeatable)--egress-allow-port PORT — Restrict allowed CIDRs to this TCP port (repeatable)
curl -X POST http://localhost:8080/v1/sandboxes \
-H "Content-Type: application/json" \
-d '{
"template": "python",
"mode": "ephemeral",
"timeout": "10m",
"size": "shared-cpu-2x",
"env": {
"OPENAI_API_KEY": "sk-..."
}
}'
Extending the timeout
Use keepalive to extend the sandbox’s lifetime before it expires:
zwrm sandbox keepalive sbx_abc123 --timeout 30m
curl -X POST http://localhost:8080/v1/sandboxes/sbx_abc123/keepalive \
-H "Content-Type: application/json" \
-d '{"timeout": "30m"}'
The maximum timeout is 24 hours (86400s). Keepalive requests exceeding this are clamped to the maximum.
Executing commands
Run a command inside the sandbox. The command executes inside the VM via the in-VM agent daemon and returns stdout, stderr, exit code, and duration.
# Simple command
zwrm sandbox exec sbx_abc123 -- python3 -c "print('hello')"
# With timeout and working directory
zwrm sandbox exec sbx_abc123 --timeout 60s --workdir /app -- make test
curl -X POST http://localhost:8080/v1/sandboxes/sbx_abc123/execute \
-H "Content-Type: application/json" \
-d '{
"command": "python3 -c \"import sys; print(sys.version)\"",
"timeout": "30s",
"workdir": "/home/user",
"env": {"DEBUG": "1"}
}'
{
"exit_code": 0,
"stdout": "3.12.0 (main, Oct 2 2024, 00:00:00)\n",
"stderr": "",
"duration_ms": 142
}
Default execution timeout is 30 seconds. Maximum is 5 minutes. Commands that exceed the timeout are killed with SIGKILL.
File operations
Upload
Upload files up to 100 MB. Parent directories are created automatically.
zwrm sandbox upload sbx_abc123 ./main.py /home/user/main.py
curl -X PUT http://localhost:8080/v1/sandboxes/sbx_abc123/files/home/user/main.py \
--data-binary @./main.py
Download
zwrm sandbox download sbx_abc123 /home/user/output.json ./output.json
curl http://localhost:8080/v1/sandboxes/sbx_abc123/files/home/user/output.json \
-o output.json
List directory
curl "http://localhost:8080/v1/sandboxes/sbx_abc123/files/home/user?list=true"
{
"entries": [
{"name": "main.py", "size": 1024, "type": "file", "modified": "2026-04-05T14:30:00Z"},
{"name": "output", "size": 4096, "type": "directory", "modified": "2026-04-05T14:31:00Z"}
]
}
Automatic cleanup
The reaper loop runs every 10 seconds and destroys expired sandboxes. Cleanup includes:
- Stopping the Firecracker VM process
- Removing the TAP network device
- Releasing the IP allocation
- Deleting the CoW overlay file
- Updating the database status to
destroyed
No manual intervention is required — expired sandboxes are cleaned up automatically. 
