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 demoA 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,STOPorDELETE.idleTimeout: time without activity, with an action,STOPorDELETE. 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.