Sessions

Every agent execution is a session. Statuses, exit statuses, the step timeline with live spend, session logs, and how to connect and steer.

Every agent execution is a session: a sandbox spins up with your repositories, the agent works step by step, delivers its output, and the sandbox is destroyed. The session record persists past the sandbox: what happened, why it ended, and what it cost.

How a session executes

Checks. Before anything is provisioned, Ellipsis verifies the agent is enabled, the account can start sessions, and no spend limit is exceeded. A failed check cancels the session here; nothing executes.
Sandbox creation. An isolated sandbox is created with the session's repositories cloned: the ones the config declares plus any the trigger brings (a PR mention adds that PR's repository).
Execution. The agent works step by step. Every step is recorded as it happens: assistant output, tool calls, tool results, tokens. Spend updates live, and the session streams to the dashboard, the CLI (--watch), and the API in real time.
Finalization. The output is stored, costs are totaled, and the sandbox is destroyed. Teardown always happens, success or failure.

On conversational surfaces (a PR, a Slack thread, a Linear issue), a trigger starts a durable conversation rather than a single-shot session: later events on the same surface continue it, and it renders as one session with turns.

Statuses

status is where a session is in that lifecycle:

`status`	Meaning
`scheduled`	Accepted and queued; nothing has started yet.
`creating_sandbox`	The sandbox is being provisioned and repositories cloned.
`running`	The agent is working.
`retrying`	A transient infrastructure failure interrupted the session; it will re-execute from scratch.
`completed`	Finished its task.
`error`	Ended on an unrecoverable failure.
`cancelled`	Stopped during checks, before executing.
`stopped`	A user stopped it mid-flight.

Laptop sessions (Claude Code sessions synced from a developer's machine) are ingested rather than executed, so they only move between running and completed as syncs arrive, and carry no exit status.

Exit statuses

Terminal sessions also carry an exit_status: the reason they ended, so a budget cutoff reads differently from a crashed tool call. It is empty until the session reaches a terminal status.

`exit_status`	The session ended because
`completed`	It finished normally.
`budget_hit`	It reached a per-session or trailing spend cap.
`payment_required`	The account has no credits or payment method.
`tool_call_failed`	An API, tool, or MCP call failed unrecoverably.
`lifecycle_hook_failed`	An `image.setup`, `post_start`, or `post_clone` script exited non-zero.
`missing_repo_access`	The Ellipsis GitHub App lacks access to a repository the session needs.
`missing_token_permissions`	The config's `sandbox.github.permissions` requests more than the installation was granted.
`missing_sandbox_variables`	The config names a `sandbox.variables` entry with no stored value.
`cancelled`	A pre-execution check failed.
`interrupted`	An infrastructure failure ended it mid-flight.
`error`	Any other unrecoverable error.
`stopped`	A user stopped it.

A session that hits its cap stops mid-task and records budget_hit; a runaway agent fails loudly, never silently. Raise a single session's budget with a per-run override rather than the config (see Billing).

The timeline

The session page in the dashboard records everything the agent did, live while it runs and permanently after:

Every step, in order: assistant output, each tool call with its input and result, and per-step token counts.
Per-turn timing and cost. In a conversation, each message and the turn that answered it, with what that turn took and spent.
Total cost, broken down into model tokens, sandbox CPU, sandbox memory, and the Ellipsis fee.
The config snapshot the session executed. Editing the file later never changes what a past session shows, and replay re-runs the snapshot, not the current config.
The trigger: the person or event that started it.

The same data is available everywhere sessions appear: agent session get session_7Hq2mX4p for status and cost, agent session record session_7Hq2mX4p for the stored transcript, and GET /v1/sessions/{session_id} over the API.

Session logs

The session log is the complete ordered history of a session: agent output, tool calls, thinking, lifecycle events, sandbox output, and messages. The dashboard timeline is the live view of it; the archive is downloadable as one file:

$ agent session log session_7Hq2mX4p -o session.jsonl

Over the API, GET /v1/sessions/{session_id}/log returns the download manifest. While a session is still running, the archive can trail the live feed; re-run the download shortly for the rest.

Connect and steer

A running session is not fire-and-forget: watch it live, send it messages, and stop it.

From the CLI, agent session connect opens the session in your terminal: the conversation so far, live output as it happens, and a composer to send messages the agent picks up at its next turn boundary. agent session start --connect starts a session and drops straight into that view. Quitting leaves the session running. Flags and transcripts: CLI sessions.

From the dashboard, opening a session lands in the same view: the live transcript of what the agent is doing, a header with status and spend, a reply box, and a Stop button.

A message sent mid-session redirects the agent without restarting it, like typing to Claude Code while it works. The reply box appears only where a send would succeed: a session you started yourself (CLI, API, or dashboard) whose agent is interactive. Sessions a trigger started open watch-only with a note saying where to steer instead: a mention conversation is steered by replying on its Slack thread, GitHub comment, or Linear issue, where the agent's answers post; react and cron sessions run once and take no messages. Watching is never restricted, so you can follow any of your sessions from anywhere.

An agent config can opt its sessions out of messages entirely with ellipsis.interactive: false, for fire-and-forget automations that should never be redirected.

Stop an in-flight session at any time, from the dashboard's Stop button or the terminal:

$ agent session stop session_7Hq2mX4p
✓ stopped session session_7Hq2mX4p (stopped)

A stopped single-shot session is terminal (stopped). Stopping a conversation stops the current turn only; the next message re-engages it.