Skip to content

Sessions

Each session id gets its own sandbox, created on first use and stopped when idle.

A session is one conversation or task with an agent. It has an id and, while it is active, a sandbox.

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

// The app you deployed with `anchor app deploy`, by its id.
const app = client.app("support-bot");

// Today you create a session yourself. It gets its own sandbox at once.
const session = await app.createSession();
console.log(session.name, session.sandbox?.name);

const result = await session.sandbox?.exec({ command: "ls", args: ["-la"] });
console.log(result?.stdout);

await session.stop();
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"],
)

# The app you deployed with `anchor app deploy`, by its id.
app = client.app("support-bot")

# Today you create a session yourself. It gets its own sandbox at once.
session = app.create_session()
print(session.name)

if session.sandbox is not None:
    result = session.sandbox.exec({"command": "ls", "args": ["-la"]})
    print(result.stdout)

session.stop()

Not available yet.

import { Sutra } from "@mistrive/sutra";

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

const agent = await sutra.agents.get("support-bot");

// Every session: its id, state, current sandbox and who invoked it.
const { items } = await agent.sessions.list();
for (const session of items) {
  console.log(session.id, session.state, session.sandbox, session.principal);
}

// Stop one session. Its sandbox stops; the session volume is kept.
const session = await agent.sessions.get("user-42");
await session.stop();
from mistrive.sutra import Sutra

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

agent = sutra.agents.get("support-bot")

# Every session: its id, state, current sandbox and who invoked it.
for session in agent.sessions.list().items:
    print(session.id, session.state, session.sandbox, session.principal)

# Stop one session. Its sandbox stops; the session volume is kept.
session = agent.sessions.get("user-42")
session.stop()
#!/usr/bin/env bash
set -euo pipefail

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

# Every session: its id, state, current sandbox and who invoked it.
sutra agents sessions list support-bot

# Stop one session. Its sandbox stops; the session volume is kept.
sutra agents sessions stop support-bot user-42

Session ids

Choose the id yourself when you invoke the agent, for example a user id or a chat id. Requests with the same id reach the same session. If you leave the id out, Sutra assigns one.

Lifecycle

  1. The first request with a new id creates the session and its sandbox. The session is ACTIVE.
  2. When the session has had no activity for the idle timeout in the agent’s revision, its sandbox stops. The session is STOPPED.
  3. A later request with the same id gives the session new compute. Its session volume is restored, so files under its mount path are where they were.

What else survives a stop follows the sandbox’s preserved level. As it rises to DISK and MEMORY, a session keeps its whole disk and then its running processes. See Stop and start.

A session stays on the revision it started with, even after you make another revision active.

List, read and stop

agent.sessions.list() returns every session of an agent, and agent.sessions.get(id) returns one. Each session has:

Field Meaning
id The session id.
state ACTIVE or STOPPED.
revision The revision the session runs.
sandbox The session’s sandbox, while it has one.
principal The user or key that invoked the session.

Stop a session with stop() when you know it is done, instead of waiting for the idle timeout.

Who invoked it

A session records the principal that invoked it. Delegated integrations act on behalf of that principal, so a session started by one user cannot use another user’s GitHub access.

Type to search…

↑↓ navigate↵ selectEsc close