Session

A session is the unit of in-flight work in a workspace. It behaves like a Git branch, but it also owns runtime state: containers, terminal scrollback, version-control position.

What a session owns

• Filesystem state — your edits to each service's working copy.
• Container runtimes — each service in the workspace has a session-scoped runtime container.
• Version-control position — Jujutsu working copy, log, and diff.
• Terminal history — PTY sessions stay attached across reconnects.
• Chat — Codex conversations are scoped to a session.

Default session

Every workspace ships with a default session called main. Sessions you create from scratch typically branch from main (or from any other session you choose).

Why sessions are useful

• Switch between feature work without rebuilding your local box.
• Hand a session off to Codex while you keep working in your own.
• Run an agent on a parallel idea without disturbing main.
• Throw away a botched experiment cheaply — sessions are disposable.

Session vs workspace

• Use a session for feature work or experiments inside an existing project.
• Use a new workspace when the work is a different project or needs different services.

API surface

Under /api/v1/sessions:

• POST /sessions — create.
• GET /sessions — list across the org.
• GET /sessions/{id} — read.
• GET /sessions/{workspace_id}/sessions — list within a workspace.
• DELETE /sessions/{id} — delete.

Most workspace-scoped endpoints (/workspace/{session_id}/...) are actually session-scoped — the session id is the routing key.