Sessions
A session is a conversation with Claude Code or Codex in its own cloud environment. The agent keeps working when you close the page or disconnect.
Start a session
In the dashboard, describe the task on Home and click New session. From a terminal:
From code:
Replace cloud_agent_environment and api-repo with your environment and repository; without an environment, the session uses the default environment. budget caps the session at $5. Keep the session ID to check on it later. To set up the client, see the Python or TypeScript SDK and API authentication.
Follow the work
The dashboard and the CLI show messages and tool calls as they happen. To reattach the CLI to a running session, run ellipsis session get <session-id> --watch. From code, wait for your prompt to be answered.
wait() returns when the session is idle or closed, with how the message ended, one of completed, failed, stopped, or cancelled. Check status before treating the task as done. error explains a failed, stopped, or cancelled message, with the same reason and detail the session carries. A timeout stops your client from waiting, not the agent. To stream messages as they happen, see the Python or TypeScript SDK. For what each status means, see Lifecycle.
Retrieve a session
Get a handle by ID at any time, for example after your application restarts.
Send a follow-up
In the dashboard, type in Reply to the agent... and click Send. In the CLI, type in the session view. From code:
A follow-up continues the same conversation and workspace. wait() then waits for that message to be answered. A message sent while the agent is working is answered after the one it is on. Only the person who started a session can message it. Sessions started by a mention take replies in their GitHub, Slack, or Linear thread. A closed session can't take follow-ups. conversation.prompting says whether a message would be accepted. See Lifecycle.
Run a one-off task
Set conversation.interactive to false when you won't send follow-ups. The session closes when its message is answered and its environment is deleted. Its messages and results stay available. To save a task and run it again or on a schedule, use Agents.
Inspect the result
The session carries its uncommitted changes, commits, and pull requests in scm.github. A file left out of the diff to keep it under 100 KB has a null patch.
Cost and records
cost.total and budget are in thousandths of a cent, so divide by 100,000 for dollars. Follow-ups share the budget. Each message's message_ended record carries what answering it cost. Read them with GET /v1/sessions/{id}/records. See Pricing for rates, or download the session history.
Stop a session
Click Stop in the dashboard. In the CLI, type /stop in the session view or run ellipsis session stop <session-id>. From code:
Stopping ends the message the agent is on with stopped and cancels any queued ones. The session's status becomes idle and it can still take follow-ups. Stopping a session whose status is idle or closed fails with 409. Disconnecting doesn't stop the agent.