Sandboxes

A sandbox is an isolated Linux (Ubuntu) machine you start through the API or the dashboard, use, and stop when you are done. Use one to run code an agent wrote, build a project, preview a web app, or drive a browser for a few minutes.

The machine is private to that sandbox. It has no access to your Zavu account, to your other sandboxes, or to any secret you did not give it.

Pricing

Billed from your prepaid balance:

• $0.01 per start, each time a sandbox is created, resumed or copied. A sandbox that fails before it ever runs gets it back.
• Machine time per second while the sandbox is starting or running, with a one-minute minimum per run.
• A stopped sandbox costs nothing. Its disk is kept 14 days.
• A saved snapshot costs $0.07 per started UTC day while you keep it.

Machine time counts against your monthly spend cap, and appears as Sandboxes in your usage.

Lifecycle

CodeCopy
starting ──▶ running ──▶ stopping ──▶ stopped ──▶ (resume) ──▶ starting
    │            │                        │
    └──▶ failed ◀┘                        └──▶ 14 days later: disk deleted

When it stops

A running sandbox is stopped for you when:

• its timeoutSeconds passes (default 1 hour, max 24 hours; checked every minute),
• your balance, or what is left of your monthly spend cap, no longer covers 15 more minutes of it,
• your team leaves its paid plan.

Send "timeoutSeconds": null on create or resume to turn the first one off: the sandbox runs until you stop it, and the other two still apply. It reads back as null, and it is billed for every second it runs, so stop it when you are done.

Ephemeral sandboxes

Send "ephemeral": true on create for a sandbox whose disk is never saved. Stopping it erases the disk: it reads back as stopped with expiresAt equal to stoppedAt, and resume answers 409 sandbox_expired. It cannot be copied or saved as a snapshot. Read what you need from it before you stop it.

Webhooks

Set up the project webhook and subscribe to these events to know when a sandbox changes state without polling. They matter most for the stops you did not ask for: a timeout, a balance or spend cap that runs out, or the team leaving its paid plan.

data.sandbox (or data.snapshot) is the object GET returns, read after the change, so you do not need a second call. stopReason is requested (you stopped it), timeout, insufficient_balance, spend_cap_reached, plan or provider, and GET /v1/sandboxes/{sandboxId} returns it too.

TypeScriptcURLCopy
await zavu.invitations.webhook.configure({
  url: "https://your-app.com/webhooks/zavu",
  events: ["sandbox.stopped", "sandbox.failed"],
});

This replaces the events the webhook had: send every event you want to keep. A failed resume is not announced, because the sandbox stays stopped and the call that resumed it already returned the error. Deliveries can repeat or arrive out of order: deduplicate by the event id and trust status over arrival order.

In the dashboard

Agents › Compute sandboxes does everything in these guides on screen: start, stop, resume, copy and delete sandboxes, run commands, expose ports, open the desktop or SSH, and keep saved snapshots, share codes and environments. Anything you do there, you can do through the API, and the other way round.

Limits

Errors

Every field is in the Sandboxes section of the API reference, starting at Create a sandbox.