Skip to content

Sandboxes

The sandbox is the one compute primitive in Sutra. Create, stop, start and delete it.

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.

import { AnchorClient } from "@mistrive/anchor";

const client = new AnchorClient({
  baseUrl: "https://anchor.jgcp.mistrivedev.com",
  token: process.env.SUTRA_API_KEY,
  project: process.env.SUTRA_PROJECT,
});

// Today the one limit is maxDuration: the sandbox stops when it ends.
// Without it, the sandbox runs until you stop or delete it.
const sandbox = await client.create({ sandbox: { maxDuration: "3600s" } });
console.log(sandbox.name);

const stopped = await sandbox.stop();
console.log(stopped.stopReason); // user_requested

// A stopped sandbox cannot be started again today. Delete it.
await sandbox.delete();
import os

from mistrive_anchor import AnchorClient

client = AnchorClient(
    base_url="https://anchor.jgcp.mistrivedev.com",
    token=os.environ["SUTRA_API_KEY"],
    project=os.environ["SUTRA_PROJECT"],
)

# Today the one limit is maxDuration: the sandbox stops when it ends.
# Without it, the sandbox runs until you stop or delete it.
sandbox = client.create({"sandbox": {"maxDuration": "3600s"}})
print(sandbox.name)

stopped = sandbox.stop()
print(stopped.stop_reason)  # user_requested

# A stopped sandbox cannot be started again today. Delete it.
sandbox.delete()
#!/usr/bin/env bash
set -euo pipefail

# Assumes you ran `anchor auth login` with a project (see the Quickstart).
# Today the id of a deleted sandbox cannot be used again, so pick a new one.
sandbox="demo-$(date +%s)"
anchor sandbox create --name "$sandbox"
anchor sandbox get "$sandbox"

# Prints the operation and returns before the sandbox has stopped.
anchor sandbox stop "$sandbox"

# A stopped sandbox cannot be started again today. Delete it.
anchor sandbox delete "$sandbox"
import { Sutra } from "@mistrive/sutra";

const sutra = new Sutra({
  baseUrl: "https://anchor.jgcp.mistrivedev.com",
});

const sandbox = await sutra.sandboxes.create({
  id: "demo",
  lifecycle: {
    timeout: { seconds: 8 * 3600, action: "DELETE" },
    idleTimeout: { seconds: 600, action: "STOP" },
  },
});

const stopped = await sandbox.stop();
console.log(stopped.state, stopped.preserved); // STOPPED VOLUMES

const started = await sandbox.start();
console.log(started.state); // RUNNING

await sandbox.delete();
from mistrive.sutra import Sutra

sutra = Sutra(
    base_url="https://anchor.jgcp.mistrivedev.com",
)

sandbox = sutra.sandboxes.create(
    id="demo",
    lifecycle={
        "timeout": {"seconds": 8 * 3600, "action": "DELETE"},
        "idle_timeout": {"seconds": 600, "action": "STOP"},
    },
)

stopped = sandbox.stop()
print(stopped.state, stopped.preserved)  # STOPPED VOLUMES

started = sandbox.start()
print(started.state)  # RUNNING

sandbox.delete()
#!/usr/bin/env bash
set -euo pipefail

# Assumes you ran `sutra auth login` (see the Quickstart).
sutra sandboxes create demo \
  --timeout 8h --timeout-action delete \
  --idle-timeout 10m --idle-action stop

sutra sandboxes stop demo
sutra sandboxes start demo
sutra sandboxes delete demo

A sandbox you create without a source starts from the default template. To start from another environment, see Templates and 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. Files on its own disk are not kept.
DISK Planned Its whole disk.
MEMORY Planned 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.

Type to search…

↑↓ navigate↵ selectEsc close