Chats and turns

Chat

A chat is a durable conversation with one coding-agent configuration. It owns:

• harness and model;
• system prompt;
• MCP server configuration;
• CPU, memory, disk, and sandbox snapshot;
• the sandbox identity;
• an ordered history of turns.

The sandbox is stopped after a turn finishes and resumed for the next turn. This ends active compute while preserving the working environment.

Turn

A turn is one prompt executed inside a chat. It owns:

• the input prompt;
• lifecycle and agent events;
• status, output, and error;
• per-turn input files and repositories;
• output artifacts;
• billable sandbox duration and resource size.

Turn identifiers are returned as soon as a run is accepted.

Creating a chat

Omit chat_id and provide the initial configuration:

{
  "prompt": "Inspect the repository and fix the failing tests.",
  "harness": "claude",
  "model": "claude-opus-4-8",
  "provider_api_key": "sk-ant-...",
  "system_prompt": "Prefer small, well-tested changes.",
  "instance": {
    "cpu": 4,
    "memory": 8
  }
}

Epho creates the chat and its first processing turn in one transaction.

Adding a turn

Resume a chat by sending its identifier:

{
  "chat_id": "01K...",
  "prompt": "Now document the behavior.",
  "provider_api_key": "sk-ant-..."
}

The prior chat configuration is inherited. The new request does not need to repeat the harness or model.

Turn lifecycle

A turn begins as processing. Lifecycle status events make infrastructure progress visible before the harness produces output:

Terminal statuses are:

• completed
• failed
• timed_out
• canceled

A terminal turn cannot move back into processing.

Concurrency rules

Only one turn may be in progress inside a particular chat. Starting another turn in that chat before the current one settles returns 409 Conflict.

Teams can run multiple chats concurrently. The default team cap is five active turns; work above the cap stays queued and emits the queued phase.

Isolation

Every API key is team-scoped. Epho resolves a chat through the authenticated team before resolving its turns. A missing identifier and an identifier owned by another team both return 404.