---
title: "Sessions"
description: "Each session id gets its own sandbox, created on first use and stopped when idle."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.jgcp.mistrivedev.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions

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

## 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](https://docs.jgcp.mistrivedev.com/sandboxes/#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.

:::note[Today]
Today you create a session with `createSession` (`create_session` in Python), and its sandbox starts at once. Sutra picks the id. There is no call to list sessions, no idle stop and no CLI command, so stop each session yourself when you are done.

A session's sandbox opens no port and has no time limit unless the create sets them, in `session.sandbox`, as for any sandbox. See [Ports](https://docs.jgcp.mistrivedev.com/sandboxes/ports/) and [Sandboxes](https://docs.jgcp.mistrivedev.com/sandboxes/#lifecycle-policy).
:::

Source: https://docs.jgcp.mistrivedev.com/agents/sessions/index.mdx
