How a session executes
The session lifecycle, statuses, steps, and what each session records.
Every agent execution is a session. Understanding the lifecycle tells you what any status means, why a session ended, and where its money went.
The lifecycle
A session moves through four phases:
- Checks. Before anything is provisioned, Ellipsis verifies the agent is enabled, the account can start workflows, 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, and cost. Spend updates live, and the session streams to the dashboard, CLI (
--watch), and API in real time. - Finalization. The output is stored, costs are totaled, and the sandbox is torn down. Teardown always happens, success or failure.
Statuses
status is where the session is in that lifecycle:
status | Meaning |
|---|---|
scheduled | Accepted, waiting for a worker. |
creating_sandbox | Provisioning the sandbox and cloning repositories. |
running | The agent is working. |
retrying | A transient infrastructure failure interrupted the session before the agent acted; 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. |
Exit statuses
Terminal sessions also carry an exit_status: the reason they ended, so a budget cutoff reads differently from a crashed tool call.
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 | A post_start or post_clone hook exited non-zero. |
missing_repo_access | The Ellipsis GitHub App lacks access to a repository the session needs. |
cancelled | A pre-execution check failed. |
interrupted | The worker died mid-session. |
error | Any other unrecoverable error. |
stopped | A user stopped it. |
What each session records
A session permanently stores: the config snapshot it executed (editing the file later never changes what a past session shows), the source that started it (cron, react, mention, manual, api, or cli), attribution to the person or event behind it, its full step timeline, per-model token usage, and cost broken down into token spend, sandbox CPU, sandbox memory, and Ellipsis fee.
The snapshot is also what replay re-executes: a replayed session reproduces the session as it was, not as the config is now.
Following a session
- Dashboard: the session detail page streams steps live and keeps the full timeline after.
- CLI:
agent session get session_7Hq2mX4p --watchfollows until terminal, or stop it early withagent session stop session_7Hq2mX4p. - API:
GET /v1/sessions/{session_id}for state, the WebSocket stream for live output with resume.