How a run executes
The run lifecycle, statuses, steps, and what each run records.
Every agent execution is a run. Understanding the lifecycle tells you what any status means, why a run ended, and where its money went.
The lifecycle
A run 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 run here; nothing executes.
- Sandbox creation. An isolated sandbox is created with the run'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 run 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 run 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 run 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 runs also carry an exit_status: the reason they ended, so a budget cutoff reads differently from a crashed tool call.
exit_status | The run ended because |
|---|---|
completed | It finished normally. |
budget_hit | It reached a per-run 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 run needs. |
cancelled | A pre-execution check failed. |
interrupted | The worker died mid-run. |
error | Any other unrecoverable error. |
stopped | A user stopped it. |
What each run records
A run permanently stores: the config snapshot it executed (editing the file later never changes what a past run 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 run reproduces the run as it was, not as the config is now.
Following a run
- Dashboard: the run detail page streams steps live and keeps the full timeline after.
- CLI:
agent run get runs_7Hq2mX4p --watchfollows until terminal. - API:
GET /v1/agents/runs/{run_id}for state, the WebSocket stream for live output with resume.