Workspaces & sessions

A workspace is a single agent session: an isolated Docker container + a conversation history + a Postgres row tracking metadata. Internally we also call them “sessions”. The session_id is the primary key.

Lifecycle

created → active → idle → paused → resumable → expired

• active — container is running, agent is processing or waiting for input.
• idle — container running but no activity. Eligible for pause after WORKSTATION_IDLE_PAUSE_SECS.
• paused — Docker container paused (memory preserved, CPU not consuming). Resume on next message.
• resumable — container was killed but data volume survives (persistent_sessions profile flag). New container spins up on next message; workspace files are re-mounted.
• expired — past expires_at. Container gone, row still in DB for history. Resurrection via session.resume will replay the EventLog transcript to rebuild context.

Persistence model

Per profile, you choose one of two models via the persistent_sessions flag:

Mode	What it gives you	Trade-off
Ephemeral (default)	Fresh container per session; no disk state survives between turns.	Faster cold-start, no surprises, no quota usage.
Persistent	Docker named volume holds /workspace. Re-attached on resume.	Files persist; quota counts against WORKSTATION_VOLUME_TTL_DAYS.

For most agents (chat, summarization, finance) ephemeral is right. For “I’m building a project across many sessions” — persistent.

Workspaces in the dashboard

The chat sidebar groups workspaces into Active (recently touched) and Earlier (older). Filters:

• Status filter (active, idle, paused, expired) via the dropdown.
• Search (text match on name).
• Pinned, starred, archived flags (PATCH /v1/workspaces/:id).

Playbook-fired workspaces (session_id starts with pb-) are hidden by default to keep the list clean. They appear once you’ve claimed a Telegram thread on them — see Telegram integration and feature #18.

API surface

Endpoint	Purpose
GET /v1/workspaces	List your workspaces (filterable by status, paginated).
GET /v1/workspaces/:id	One workspace.
PATCH /v1/workspaces/:id	Rename, star, pin, archive, set tags, change model override.
DELETE /v1/workspaces/:id	Permanently delete (volume + row).
GET /v1/workspaces/:id/events	Full event-log transcript (for replay, audit, debugging).
GET /v1/workspaces/:id/files	Browse the workspace filesystem (/workspace/ inside the container).
POST /v1/workspaces/:id/upload	Multipart upload to the workspace.

See the REST reference for full request/response shapes.

Session ↔ container relationship

A workspace always has at most one container alive at a time. The orchestrator’s dispatchSession figures out which case applies:

1. Container alive (status === "running") → reuse.
2. Container paused → unpause + reuse.
3. Persistent + container dead but volume survives → spin up a new container, attach the volume, re-run setup commands.
4. Ephemeral + container dead → create fresh.
5. No record → create from scratch + register the workspace row.

Note

The expires_at column is a watermark — the reaper looks for rows past it during idle sweeps. It’s not a hard “session goes away at this moment” guarantee. Active conversations extend expires_at automatically.