Sessions

A session is one agent working in the cloud. Start one with `agent`, steer it live, stop it, and read what it did and cost afterward.

A session is one agent working: a sandbox comes up with your repositories cloned, the agent works step by step, and the sandbox is destroyed. The record outlives the sandbox: every step, what it cost, and why it ended.

Start one

agent "Fix the flaky test in ci/"

Inside a checkout, the repository you are standing in is cloned into the sandbox. Name where else to run, which model, and how much it may spend:

agent -e cloud_agent_environment --model claude-sonnet-5 --budget 5 "Fix the flaky test in ci/"

Flag	Meaning
`-e, --environment <name>`	Run in a saved environment, by name or id.
`-r, --repo <owner/name>`	Clone a repository into the sandbox (repeatable).
`--model <id>`	The model for this session (`agent model list`).
`--budget <usd>`	The most this session may spend, in dollars.
`-f, --config-file <path>`	Start from a config file (YAML or JSON): an automation file, whose `session:` block is used, or a bare session config.
`-t, --template <slug>`	Start from a maintained template (`agent template list`).
`--rebuild`	Skip the image cache and provision from a fresh build.

The model and budget you leave out come from your organization's settings: the default model and the per-session budget ceiling. A --budget above the ceiling is refused, not clamped. The environment is never defaulted: leave -e out and the session runs in the built-in basic sandbox. With no prompt at all, agent opens the launcher: pick an environment and a model, type the prompt there.

Inside a session

Starting a session drops you into it: the transcript so far, live output as it happens, and a composer. Anything you type is delivered at the agent's next turn boundary, like typing to Claude Code while it works. Ctrl-C leaves the session running in the cloud; agent session connect <id> reopens it, and the dashboard shows the same view with a Stop button.

An automation's sessions behave the same way except that they take no messages from here: a session started by a mention is steered where the mention was (the pull request thread, the Slack thread, the Linear issue), and sessions started by a cron or a repository event run once and take no follow-ups.

Conversations

A session you start, or one a mention starts, is a conversation: the agent answers, waits, and picks up the next message with everything it already said and did as context, including the working tree.

Each surface gets exactly one conversation. A pull request, a GitHub issue, a Linear issue, and a Slack thread are each one conversation; every later mention there continues it. Each agent "..." is a new conversation.
After a turn the conversation stays warm for 10 minutes, and the sandbox bills like any other sandbox time. After that its state is snapshotted and the sandbox is destroyed; the next message resumes it in a fresh sandbox, working tree intact, with fresh credentials.
The whole conversation runs on one budget. When it is spent, the conversation stops taking turns and records budget_hit.
A failed turn does not end the conversation. Stopping stops the current turn only; the next message re-engages it.

From scripts

The same session over HTTP, with the same flat body the CLI sends:

curl -X POST https://api.ellipsis.dev/v1/sessions \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "cloud_agent_environment",
    "prompt": "Fix the flaky test in ci/",
    "claude": {"model": "claude-sonnet-5"},
    "budget": 5.0
  }'

environment is a saved environment's name or id, or an inline environment object for this session only. The response is the created session; poll GET /v1/sessions/{session_id}, or stream it over the WebSocket. Every field: POST /v1/sessions. To run a saved automation from a script, invoke it instead: Automations.

The CLI's subcommands cover the rest for scripts and CI:

agent session get session_3Fp9dR2k --watch     # block until it settles
agent session list --days 7                    # recent sessions
agent session stop session_3Fp9dR2k
agent session export session_3Fp9dR2k -o session.jsonl

Statuses

status is where a session is in its 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, or waiting for your next message.
`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.

Terminal sessions also carry an exit_status, the reason they ended:

`exit_status`	The session ended because
`completed`	It finished normally.
`budget_hit`	It reached its budget or a trailing spend limit.
`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 asked for more GitHub permissions than the installation was granted.
`missing_sandbox_variables`	The config names an `environment.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.

Cost and records

Every session records its total cost split four ways (model tokens, sandbox CPU, sandbox memory, the platform fee) with per-step spend on the timeline, the exact definition it ran frozen at start, who or what started it, and the full log. The log downloads as one file with agent session export, or GET /v1/sessions/{session_id}/export. Editing an automation later never changes what a past session shows.