---
title: "Sandboxes"
description: "The sandbox is the one compute primitive in Sutra. Create, stop, start and delete it."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.jgcp.mistrivedev.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandboxes

A sandbox is an isolated microVM with its own disk, network and processes. It is the one compute primitive in Sutra. Agents, services and the code you run directly all run in sandboxes, and you can list and inspect every one of them.

## Create a sandbox

Create a sandbox with a lifecycle policy, stop it, start it again and delete it.

A sandbox you create without a source starts from the default template. To start from another environment, see [Templates](https://docs.jgcp.mistrivedev.com/sandboxes/templates/) and [Snapshots](https://docs.jgcp.mistrivedev.com/sandboxes/snapshots/).

## States

| State | Meaning |
| --- | --- |
| `CREATING` | Sutra is placing the sandbox and booting it. |
| `RUNNING` | The sandbox is up. You can run processes, use files and reach its ports. |
| `STOPPING` | Sutra is releasing the sandbox's compute. |
| `STOPPED` | The sandbox has no compute. It keeps what `preserved` says. |
| `STARTING` | Sutra is giving a stopped sandbox compute again. |
| `DELETING` | Sutra is removing the sandbox. |
| `FAILED` | The sandbox could not reach or stay in `RUNNING`. `stateReason` says why. |

Create, stop, start and delete wait for the sandbox to reach its next state. Pass `wait` to limit how long the call waits; the change continues after the call returns.

## Stop and start

Stop releases a sandbox's compute. Start gives it compute again. These are the only two verbs: there is no separate way to suspend a sandbox.

A stopped sandbox reports what it kept in `preserved`:

| Value | What the sandbox keeps |
| - | - |
| `VOLUMES` | Its [volumes](https://docs.jgcp.mistrivedev.com/sandboxes/volumes/). Files on its own disk are not kept. |
| `DISK` | Its whole disk. |
| `MEMORY` | Its disk and memory, so processes continue where they were. |

The level rises as the platform supports more. Your code stays the same: you call stop and start, and read `preserved` if you need to know.

## Lifecycle policy

A lifecycle policy stops or deletes a sandbox for you. It has three settings:

- `timeout`: wall-clock time since the sandbox last started, with an action, `STOP` or `DELETE`.
- `idleTimeout`: time without activity, with an action, `STOP` or `DELETE`. Activity is an API call on the sandbox, a run call that is still waiting, or traffic on one of its ports.
- `stoppedRetention`: how long a stopped sandbox is kept before it is deleted.

A sandbox has none of them unless you set them, so it runs until you stop or delete it. That makes a sandbox usable as a development machine that is always there. You can ask for a timeout of any length.

Your organization or project can set a policy of its own: the defaults a sandbox gets when it sets none, and the limits a sandbox cannot exceed. Change the policy of a running sandbox with `update`.

## Resources

Set `resources` when you create a sandbox: CPU, memory and disk. A sandbox you create without them gets the defaults of its template. The resources of a sandbox are fixed when it is created.

:::note[Today]
Today the one limit of a sandbox is `maxDuration`, from 1 second to 2147483647 seconds (about 68 years). It counts from the start of the sandbox. When it ends, the sandbox stops and its `stopReason` is `timeout`. A sandbox created without it runs until you stop or delete it.

You can stop a sandbox, but you cannot start it again yet, so delete it when you are done. Delete stops a running sandbox first. The id of a deleted sandbox cannot be used again.

A create that fails before the sandbox starts, for example because of an integration you cannot use, leaves the sandbox in the state `ERROR`. Delete it.

Without `resources` a sandbox gets 1 vCPU, 512 MiB of memory and 512 MiB of disk. The most a sandbox can have is 4 vCPUs, 4096 MiB of memory and 8192 MiB of disk.

The SDKs' `create` and `stop` wait up to 300 seconds for the sandbox to reach its next state. `anchor sandbox stop` returns before the sandbox has stopped.
:::

Source: https://docs.jgcp.mistrivedev.com/sandboxes/index.mdx
