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 demorun 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 demoTo 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.