Skip to content

Processes

Run commands, terminals and code in a sandbox.

A process is anything that runs in a sandbox: a command, a terminal or a piece of code. All three are the same resource, with a kind of COMMAND, TERMINAL or CODE.

Run a process and wait

run starts a process and waits for it to end. It returns the process with its exit and its output.

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,
});

const sandbox = await client.create();

// Runs the command and waits for it to end, for at most 60 seconds.
const result = await sandbox.exec({
  command: "sh",
  args: ["-c", "echo checking; exit 3"],
  timeout: "60s",
});

// A non-zero exit is a result, not an error.
console.log(result.exitCode, result.stdout); // 3 checking

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"],
)

sandbox = client.create()

# Runs the command and waits for it to end, for at most 60 seconds.
result = sandbox.exec(
    {"command": "sh", "args": ["-c", "echo checking; exit 3"], "timeout": "60s"}
)

# A non-zero exit is a result, not an error.
print(result.exit_code, result.stdout)  # 3 checking

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"

# Prints the output. A non-zero exit code makes the command exit with 1.
anchor sandbox exec "$sandbox" -- sh -c 'echo checking; exit 3' || echo "the process did not exit with 0"

# With --json it prints the result, with the code in exit_code, and exits 0.
anchor --json sandbox exec "$sandbox" -- sh -c 'echo checking; exit 3'

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();

// Waits up to 60 seconds. If the process is still running then, it keeps
// running and the result has no exit.
const result = await sandbox.processes.run({
  shellCommand: "echo checking; exit 3",
  wait: 60,
});

// A non-zero exit is a result, not an error.
console.log(result.exit?.reason, result.exit?.code); // EXITED 3
console.log(result.stdout); // checking

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

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

sandbox = sutra.sandboxes.create()

# Waits up to 60 seconds. If the process is still running then, it keeps
# running and the result has no exit.
result = sandbox.processes.run(shell_command="echo checking; exit 3", wait=60)

# A non-zero exit is a result, not an error.
if result.exit:
    print(result.exit.reason, result.exit.code)  # EXITED 3
print(result.stdout)  # checking

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

# Assumes you ran `sutra auth login` (see the Quickstart).
sutra sandboxes create demo

# Prints the output and exits with the process's exit code.
sutra processes run demo --wait 60s -- sh -c 'echo checking; exit 3' || echo "exit code: $?"

sutra sandboxes delete demo

run waits up to wait seconds. If the process is still running when the wait ends, it keeps running and the result has no exit. Call wait on the process to wait again.

wait is how long your call waits. timeout is when Sutra ends the process. They are separate settings, and an unset timeout means the process has no limit.

Exit

A process that has ended has an exit with a reason:

Reason Meaning
EXITED The process ended on its own. code holds its exit code.
SIGNALED A signal ended the process. signal holds its name.
TIMED_OUT The process reached its timeout.
LOST Sutra lost track of the process and cannot report how it ended.

A non-zero exit code is a result, not an error. The call succeeds, and you decide what the code means. Sutra never runs a process again on its own.

Start a long-running process

start returns as soon as the process has started. Use it for servers and other work that runs in the background.

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,
});

const sandbox = await client.create();

// Returns as soon as the process has started.
const server = await sandbox.processes.start({
  processId: "server",
  command: "python3",
  args: ["-u", "-m", "http.server", "3000"],
});

// Waits up to 5 seconds for the process to end. The server keeps running.
await server.wait({ timeout: "5s" });

// Output is read by byte offset.
const logs = await server.logs({ offset: 0 });
console.log(logs.data);

// Today a process is ended with SIGKILL.
await server.kill();
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"],
)

sandbox = client.create()

# Returns as soon as the process has started.
server = sandbox.processes.start(
    {"processId": "server", "command": "python3", "args": ["-u", "-m", "http.server", "3000"]}
)

# Waits up to 5 seconds for the process to end. The server keeps running.
server.wait({"timeout": "5s"})

# Output is read by byte offset.
logs = server.logs({"offset": 0})
print(logs.data)

# Today a process is ended with SIGKILL.
server.kill()
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"

# Returns as soon as the process has started.
anchor sandbox process start "$sandbox" --process-id server -- python3 -u -m http.server 3000

# Waits up to 5 seconds for the process to end. The server keeps running.
anchor sandbox process wait "$sandbox/server" --timeout 5s
anchor sandbox process logs "$sandbox/server"

# Today a process is ended with SIGKILL.
anchor sandbox process kill "$sandbox/server"

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();

// Returns as soon as the process has started.
const server = await sandbox.processes.start({
  id: "server",
  argv: ["python3", "-m", "http.server", "3000"],
});

// Output is kept. Read it from the start, or pass a cursor to continue.
for await (const chunk of server.streamOutput()) {
  console.log(chunk.stream, chunk.data);
  if (chunk.data.includes("Serving HTTP")) break;
}

await server.signal("SIGTERM", { escalateAfter: 10 });
await sandbox.delete();
from mistrive.sutra import Sutra

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

sandbox = sutra.sandboxes.create()

# Returns as soon as the process has started.
server = sandbox.processes.start(id="server", argv=["python3", "-m", "http.server", "3000"])

# Output is kept. Read it from the start, or pass a cursor to continue.
for chunk in server.stream_output():
    print(chunk.stream, chunk.data)
    if "Serving HTTP" in chunk.data:
        break

server.signal("SIGTERM", escalate_after=10)
sandbox.delete()
#!/usr/bin/env bash
set -euo pipefail

# Assumes you ran `sutra auth login` (see the Quickstart).
sutra sandboxes create demo

# Returns as soon as the process has started.
sutra processes start demo --id server -- python3 -m http.server 3000

sutra processes output demo server
sutra processes signal demo server SIGTERM --escalate-after 10s

sutra sandboxes delete demo

To end a process, send it a signal. Pass escalateAfter to send SIGKILL if it is still running after that many seconds.

Output

Sutra keeps the output of every process. Read it in pages with readOutput, or stream it with streamOutput. Each chunk carries a cursor: pass it back to continue from where you stopped.

Terminals and code

A TERMINAL process runs in a pseudo-terminal with columns and rows. Write to it with writeInput, change its size with resize, and attach to it over a two-way stream.

A CODE process runs a snippet in a language: python, javascript, typescript or bash. It has the same exit and output as a command.

Type to search…

↑↓ navigate↵ selectEsc close