Reference: interactive generative UI components, the event protocol and CLI commands; REST endpoints live in the OpenAPI schema --- # Event Reference > All Everruns event types, with schemas and SSE examples for the common ones: input, output, tool, lifecycle, and error events. Source: This page lists every event type in the Everruns event protocol and documents the schema of the most common ones. Types without a section below are listed in the table with a short description. ## All event types | Event type | Description | | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`input.message`](#inputmessage) | User message submitted to the session. | | [`output.message.started`](#outputmessagestarted) | Assistant message started. | | [`output.message.delta`](#outputmessagedelta) | Streaming chunk of assistant text. | | [`output.message.completed`](#outputmessagecompleted) | Assistant message finished and persisted. | | [`conversation.message`](#conversationmessage) | An agent that uses explicit communication sent a message with `send_message`. | | `output.message.replaced` | Clients discard streamed text for the turn and show a replacement; the next `output.message.completed` carries it. | | [`turn.started`](#turnstarted) | Turn began. | | [`turn.completed`](#turncompleted) | Turn finished successfully. | | [`turn.failed`](#turnfailed) | Turn failed with an error. | | [`turn.completion_checked`](#turncompletion_checked) | A finishing turn was reviewed; says whether it finished or continued automatically. | | [`turn.credit_shortfall`](#turncredit_shortfall) | The provider refused a request for lack of credits; says whether the turn retried smaller, waits for credits, resumed, or gave up. | | `turn.sealed` | Turn stopped without success or error (for example repeated crash-reclaims or exhausted work budget); carries a `reason`. | | [`turn.cancelled`](#turncancelled) | Turn cancelled by the user. | | [`reason.started`](#reasonstarted) | LLM inference step began. | | [`reason.completed`](#reasoncompleted) | LLM inference step finished. | | `reason.recovered` | A reason step was recovered after a failure. | | [`reason.thinking.started`](#reasonthinkingstarted) | Model thinking started. | | [`reason.thinking.delta`](#reasonthinkingdelta) | Streaming chunk of model thinking. | | [`reason.thinking.completed`](#reasonthinkingcompleted) | Model thinking finished. | | [`reason.item`](#reasonitem) | Provider reasoning item identity and safe summary text; opaque replay payloads are excluded. | | [`act.started`](#actstarted) | Tool execution phase began. | | [`act.completed`](#actcompleted) | Tool execution phase finished. | | [`tool.started`](#toolstarted) | A tool call began. | | [`tool.completed`](#toolcompleted) | A tool call finished. | | `tool.progress` | Progress update from a running tool. | | `tool.output.delta` | Streaming chunk of tool output. | | `tool.call_requested` | A client-side tool call is waiting for a result from the client. | | `tool.reviewed` | The [auto approval](https://everruns.com/docs/capabilities/tool-approval/#auto-mode) reviewer allowed, blocked or handed a tool call to a person. Carries `verdict`, `stage`, `rule` and `reason`. | | `tool.call_repaired` | A malformed tool call was repaired, or repair was attempted, by the `tool_call_repair` capability. | | `tool.hosted_call` | A provider-executed (hosted) tool call changed state. | | `tool.nested_call` | A tool a shell script called through `tools` ([Shell Code Mode](https://everruns.com/docs/capabilities/shell-code-mode/)) finished, was refused, or stopped the script for approval. Carries the parent `bash` call id. | | `transcript.repaired` | The conversation transcript was repaired before a provider request. | | `capability.usage` | Usage of a capability by the agent. | | [`llm.generation`](#llmgeneration) | One LLM call: model, usage, and timing. | | [`session.started`](#sessionstarted) | Session created. | | [`session.activated`](#sessionactivated) | Session started working on a turn. | | [`session.idled`](#sessionidled) | Session returned to idle. | | `session.title.updated` | Session title changed. | | `session.model.changed` | Model override differs from the previous turn’s. | | [`sandbox.instance_lost`](#sandboxinstance_lost) | Managed Sandbox compute disappeared and will be replaced. | | [`sandbox.recovered`](#sandboxrecovered) | Managed Sandbox compute was replaced and its durable workspace restored. | | [`environment.instance_lost`](#sandboxinstance_lost) | Legacy compatibility name for `sandbox.instance_lost`. | | [`environment.recovered`](#sandboxrecovered) | Legacy compatibility name for `sandbox.recovered`. | | `timer.set` | The session set a timer, such as a schedule. | | `timer.fired` | A timer’s occurrence was delivered to the session. | | `timer.cancelled` | A timer will not fire again. | | `task.created` | Session task created. | | `task.updated` | Session task changed. | | `task.message.sent` | Message sent to a session task. | | `task.message.received` | Message received from a session task. | | `context.compacting` | Context compaction started. | | `context.compacted` | Context compaction installed a summary. | | `context.compaction.skipped` | A compaction evaluation ran but installed nothing. | | `context.compaction.failed` | A compaction attempt errored before installing. | | `dreaming.activity` | Background Memory consolidation status, note count, model, usage, and cost; excludes evidence and generated notes. See [Dreaming](https://everruns.com/docs/features/dreaming/). | | `file.written` | A session file was written. | | `budget.warning` | Budget crossed its warning threshold. | | `budget.paused` | Budget paused the session. | | `budget.exhausted` | Budget has no room left. | | `budget.resumed` | Budget resumed. | | `voice.session.started` | Voice session started. | | `voice.input_transcript.delta` | Streaming chunk of the user’s speech transcript. | | `voice.input_transcript.completed` | User’s speech transcript finished. | | `voice.output_transcript.delta` | Streaming chunk of the assistant’s speech transcript. | | `voice.output_transcript.completed` | Assistant’s speech transcript finished. | | `voice.session.ended` | Voice session ended. | | `voice.session.failed` | Voice session failed. | | `voice.output.interrupted` | The caller talked over a spoken answer; carries what was heard and what was dropped. | ## Input Events ### input.message Emitted when a user message is submitted to the session. | Field | Type | Description | | --------- | ------- | ----------------------- | | `message` | Message | The user message object | ```json { "type": "input.message", "data": { "message": { "id": "message_...", "role": "user", "content": [{"type": "text", "text": "Hello!"}], "created_at": "2024-01-15T10:30:00.000Z" } } } ``` ## Output Events ### output.message.started Emitted when the LLM starts generating a response. This marks the start of generation, not model reasoning: reasoning has its own events (see [Reasoning Events](#reasoning-events)) and its own channel. | Field | Type | Description | | --------- | ------- | ----------------------------------------------------------------------------------------------------- | | `turn_id` | string | Turn ID this output belongs to | | `model` | string? | Optional model name being used | | `phase` | string? | Best-effort phase hint: `commentary` or `final_answer`. Absent means unclassified, never “reasoning”. | ```json { "type": "output.message.started", "data": { "turn_id": "turn_...", "model": "gpt-6.2-sol" } } ``` ### output.message.delta Incremental text update during LLM generation. Events are batched (\~100ms). | Field | Type | Description | | ------------- | ------ | ----------------------------- | | `turn_id` | string | Turn ID this delta belongs to | | `delta` | string | New text since last delta | | `accumulated` | string | Total text so far | ```json { "type": "output.message.delta", "data": { "turn_id": "turn_...", "delta": "Hello", "accumulated": "Hello" } } ``` ### output.message.completed Emitted when the agent response is complete. | Field | Type | Description | | ---------- | -------------- | -------------------------- | | `message` | Message | The complete agent message | | `metadata` | ModelMetadata? | Model information | | `usage` | TokenUsage? | Token usage statistics | `message.phase` is authoritative for whether this message is intermediate `commentary` or the turn’s `final_answer`, and `message.phase_source` says whether the provider reported that phase (`provider`) or the runtime inferred it from tool-call presence (`derived`). Reasoning artifacts appear as `reasoning` content parts inside `message.content`, in the order the provider emitted them. ```json { "type": "output.message.completed", "data": { "message": { "id": "message_...", "role": "assistant", "content": [{"type": "text", "text": "Hello! How can I help?"}] }, "usage": { "input_tokens": 50, "output_tokens": 25 } } } ``` ### conversation.message Emitted when an agent that uses [explicit communication](https://everruns.com/docs/features/explicit-communication/) sends a message with the `send_message` tool. For these agents this event, not `output.message.completed`, carries what the agent said: their assistant text is recorded as `output.message.completed` with `message.phase: "commentary"` and is working notes, not a reply. | Field | Type | Description | | ---------------------- | ------- | ---------------------------------------------------------------------------------------- | | `message_id` | string | Identifier of the sent message | | `text` | string | The message as the agent wrote it, in Markdown | | `tool_call_id` | string | The `send_message` call that sent it | | `delivery` | object? | Present only when an external platform accepted the message (for example a Slack thread) | | `delivery.platform` | string | Destination platform, such as `slack` | | `delivery.channel` | string | Platform channel or conversation identifier | | `delivery.message_ref` | string | Platform message identifier | When the conversation is the session itself (web chat, API, A2A, AG-UI, MCP, FCP), `delivery` is absent and this event is the delivery. ```json { "type": "conversation.message", "data": { "message_id": "message_...", "text": "The report is ready. Revenue grew 12% quarter over quarter.", "tool_call_id": "call_abc123", "delivery": { "platform": "slack", "channel": "C0123456789", "message_ref": "1712345678.000200" } } } ``` ## Turn Lifecycle Events ### turn.started Emitted when a turn begins execution. | Field | Type | Description | | ------------------ | ------- | -------------------------------- | | `turn_id` | string | Turn identifier | | `input_message_id` | string | Message that triggered this turn | | `input_content` | string? | Optional input content preview | ```json { "type": "turn.started", "data": { "turn_id": "turn_...", "input_message_id": "message_...", "input_content": "Hello!" } } ``` ### turn.completed Emitted when a turn completes successfully. | Field | Type | Description | | ------------------------ | ----------- | ---------------------------------------------------------------------------------------------------------------- | | `turn_id` | string | Turn identifier | | `iterations` | integer | Number of reason-act iterations | | `duration_ms` | integer? | Duration in milliseconds | | `usage` | TokenUsage? | Aggregated token usage | | `input_content` | string? | Optional input content | | `final_message_id` | string? | Canonical final assistant message ID | | `final_answer_preview` | string? | Bounded final answer preview | | `time_to_first_token_ms` | integer? | First-token latency | | `tool_call_count` | integer? | Completed tool-call count | | `llm_call_count` | integer? | LLM generation count | | `issue_count` | integer? | Failed tool calls the turn recovered from. The turn still succeeded; see [Issues and errors](#issues-and-errors) | | `status` | string? | Optional completion status | | `stop_reason` | string? | How the final model call ended (`stop`, `length`, `content_filter`, …) | ```json { "type": "turn.completed", "data": { "turn_id": "turn_...", "iterations": 3, "duration_ms": 1500, "usage": { "input_tokens": 500, "output_tokens": 200 }, "final_message_id": "message_...", "final_answer_preview": "Done.", "time_to_first_token_ms": 120, "tool_call_count": 2, "llm_call_count": 3, "issue_count": 0, "status": "completed", "stop_reason": "stop" } } ``` ### turn.completion_checked Emitted when a turn that was about to finish is reviewed by the agent’s `completion_check` setting. When `action` is `continued`, an `input.message` with metadata `everruns_origin: "turn_continuation"` follows in the same turn, and the turn keeps going. | Field | Type | Description | | ------------------------- | ------- | --------------------------------------------------------------------- | | `turn_id` | string | Turn identifier | | `verdict` | string? | `achieved`, `in_progress` or `blocked`; absent when the review failed | | `reason` | string | The review’s short reason, or the failure | | `action` | string | `finished`, `continued`, `budget_exhausted` or `review_failed` | | `continuations_used` | integer | Automatic continuations this turn has used, including this one | | `max_continuations` | integer | Continuations the turn may use | | `tokens_used` | integer | Tokens the turn’s continuations have used | | `elapsed_ms` | integer | Time since the first continuation | | `continuation_message_id` | string? | The continuation input, when `action` is `continued` | ```json { "type": "turn.completion_checked", "data": { "turn_id": "turn_...", "verdict": "in_progress", "reason": "The review was announced but never submitted.", "action": "continued", "continuations_used": 1, "max_continuations": 6, "tokens_used": 0, "elapsed_ms": 0, "continuation_message_id": "message_..." } } ``` ### turn.credit_shortfall Emitted when the provider refuses a request because the account cannot pay for it (`provider_quota_exhausted`), once per decision the runtime makes about it. When the balance still covers at least 4,096 output tokens, the same request is retried once with max output tokens lowered to what it covers (`shrunk`). Otherwise the turn fails and a check for credits runs every minute for up to an hour, as a scheduled run of the session that reads the provider balance without a model call (`wait_started`, then `still_waiting` per check). When credits are back the work continues (`resumed`); when the hour runs out the turn fails with `provider_quota_exhausted` (`gave_up`). | Field | Type | Description | | ---------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `turn_id` | string | Turn identifier | | `action` | string | `shrunk`, `wait_started`, `still_waiting`, `resumed` or `gave_up` | | `requested_max_tokens` | integer? | Max output tokens the refused request asked for, when the provider said | | `affordable_tokens` | integer? | Output tokens the balance covered, when the provider said | | `max_tokens` | integer? | Max output tokens of the smaller retry (`shrunk`) | | `wait_until` | string? | When the wait ends at the latest (RFC 3339) | | `next_check_at` | string? | When the next check runs, when one was scheduled | | `balance_checked` | boolean? | `true` when a check read the provider balance (OpenRouter); `false` when the provider has no balance API and the request itself was the check | ```json { "type": "turn.credit_shortfall", "data": { "turn_id": "turn_...", "action": "wait_started", "requested_max_tokens": 65536, "affordable_tokens": 283, "wait_until": "2026-11-03T15:04:05Z", "next_check_at": "2026-11-03T14:05:05Z" } } ``` ### turn.failed Emitted when a turn fails with an error. A failed turn is always an error: the work stopped. | Field | Type | Description | | ------------ | ------- | ------------------- | | `turn_id` | string | Turn identifier | | `error` | string | Error message | | `error_code` | string? | Optional error code | ```json { "type": "turn.failed", "data": { "turn_id": "turn_...", "error": "The model provider is rate limiting requests. Please try again shortly.", "error_code": "provider_rate_limited" } } ``` ### turn.cancelled Emitted when a turn is cancelled by the user. | Field | Type | Description | | --------- | ----------- | ------------------------- | | `turn_id` | string | Turn identifier | | `reason` | string? | Cancellation reason | | `usage` | TokenUsage? | Usage before cancellation | ```json { "type": "turn.cancelled", "data": { "turn_id": "turn_...", "reason": "User requested", "usage": { "input_tokens": 100, "output_tokens": 50 } } } ``` ## Reasoning Events Model reasoning, as distinct from the `reason.started` / `reason.completed` lifecycle events further down, which mark an LLM *inference step* in the reason/act loop and are unrelated to whether the model reasoned. These events are emitted by models that expose reasoning (Anthropic Claude with thinking enabled, OpenAI GPT-5.x and o-series with reasoning effort configured, Gemini with a thinking budget, and Chat Completions models that return `reasoning_content`). Everything here belongs to the reasoning channel and must never be rendered as assistant text. ### reason.thinking.started Emitted when extended thinking begins. | Field | Type | Description | | --------- | ------- | ----------- | | `turn_id` | string | Turn ID | | `model` | string? | Model name | ```json { "type": "reason.thinking.started", "data": { "turn_id": "turn_...", "model": "claude-4-opus" } } ``` ### reason.thinking.delta Streams incremental thinking content. | Field | Type | Description | | ------------- | ------ | --------------------- | | `turn_id` | string | Turn ID | | `delta` | string | New thinking text | | `accumulated` | string | Total thinking so far | ```json { "type": "reason.thinking.delta", "data": { "turn_id": "turn_...", "delta": "Let me think about this...", "accumulated": "Let me think about this..." } } ``` ### reason.thinking.completed Emitted when extended thinking completes. | Field | Type | Description | | ---------- | ------ | ------------------------- | | `turn_id` | string | Turn ID | | `thinking` | string | Complete thinking content | ```json { "type": "reason.thinking.completed", "data": { "turn_id": "turn_...", "thinking": "I need to consider the user's request carefully..." } } ``` ### reason.item Emitted when one reasoning artifact completes. One event per provider reasoning block, in emission order. Carries identity and safe summary text only. The opaque payloads that make the artifact replayable — provider signatures and encrypted reasoning context — are deliberately excluded: they are replay state, not content, and never appear in events or on any API surface. | Field | Type | Description | | ------------- | --------- | -------------------------------------------------------------- | | `turn_id` | string | Turn ID this artifact belongs to | | `provider` | string | Provider that produced it (`anthropic`, `openai`, `google`) | | `model` | string? | Model reported by the provider | | `item_id` | string | Provider-assigned identifier, when the provider issues one | | `summary` | string\[] | Provider-curated summary segments. Never raw chain-of-thought. | | `token_count` | integer? | Reasoning tokens attributed to this artifact | ```json { "type": "reason.item", "data": { "turn_id": "turn_...", "provider": "openai", "model": "gpt-6.2-sol", "item_id": "rs_68a1f...", "summary": ["Checking the build logs before answering."], "token_count": 412 } } ``` ## Atom Lifecycle Events These events mark steps of the reason/act execution loop. `reason.*` here means “the LLM inference step”, not model reasoning — for that see [Reasoning Events](#reasoning-events). ### reason.started Emitted when LLM inference begins. | Field | Type | Description | | ---------- | -------------- | ----------------- | | `agent_id` | string | Agent ID | | `metadata` | ModelMetadata? | Model information | ```json { "type": "reason.started", "data": { "agent_id": "agent_...", "metadata": { "model": "gpt-6.2-sol" } } } ``` ### reason.completed Emitted when LLM inference completes. | Field | Type | Description | | ----------------- | ----------- | ---------------------------- | | `success` | boolean | Whether the call succeeded | | `text_preview` | string? | First 200 chars of response | | `has_tool_calls` | boolean | Whether tools were requested | | `tool_call_count` | integer | Number of tool calls | | `error` | string? | Error if failed | | `duration_ms` | integer? | Duration | | `usage` | TokenUsage? | Token usage | ```json { "type": "reason.completed", "data": { "success": true, "text_preview": "Hello! I can help you with...", "has_tool_calls": false, "tool_call_count": 0, "duration_ms": 1200, "usage": { "input_tokens": 100, "output_tokens": 50 } } } ``` ### act.started Emitted when tool execution batch begins. | Field | Type | Description | | ------------ | ------------------ | -------------------- | | `tool_calls` | ToolCallSummary\[] | Tools to be executed | ```json { "type": "act.started", "data": { "tool_calls": [ {"id": "tc_1", "name": "get_weather"}, {"id": "tc_2", "name": "search_web"} ] } } ``` ### act.completed Emitted when tool execution batch completes. | Field | Type | Description | | --------------- | -------- | ------------------------------------------------------------------------------ | | `completed` | boolean | All tools completed | | `success_count` | integer | Successful tool calls | | `error_count` | integer | Failed tool calls. Each is an issue the turn carries on from, not a turn error | | `duration_ms` | integer? | Total duration | ```json { "type": "act.completed", "data": { "completed": true, "success_count": 2, "error_count": 0, "duration_ms": 500 } } ``` ### tool.started Emitted when individual tool execution begins. | Field | Type | Description | | ----------- | -------- | ----------------------------- | | `tool_call` | ToolCall | Full tool call with arguments | ```json { "type": "tool.started", "data": { "tool_call": { "id": "tc_1", "name": "get_weather", "arguments": {"city": "London"} } } } ``` ### tool.completed Emitted when individual tool execution completes. | Field | Type | Description | | ------------------------------ | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tool_call_id` | string | Tool call ID | | `tool_name` | string | Tool name | | `success` | boolean | Whether it succeeded | | `status` | string | “success”, “error”, “timeout”, “cancelled” | | `result` | ContentPart\[]? | Result content | | `error` | string? | Error message | | `severity` | string? | `issue` when the call failed; absent on success. See [Issues and errors](#issues-and-errors) | | `duration_ms` | integer? | Wall-clock duration | | `worker_thread_cpu_ns` | integer? | Observed worker-thread CPU during executor-future polls; absent means unknown | | `executed_arguments` | JSON? | Arguments the tool actually ran with. Present only when a `pre_tool_use` hook rewrote the arguments the model sent (those stay on `tool.started`). Values under credential-named keys such as `password`, `access_token`, or `Authorization` read `[REDACTED]`, and credential-looking text inside other values (bearer tokens, common provider API keys, URL user info) is replaced with `[REDACTED]`. Larger than 8 KiB serialized, it is a truncated JSON string. | | `executed_arguments_truncated` | boolean? | `true` when `executed_arguments` is truncated | ```json { "type": "tool.completed", "data": { "tool_call_id": "tc_1", "tool_name": "get_weather", "success": true, "status": "success", "result": [{"type": "text", "text": "Sunny, 22°C"}], "duration_ms": 250 } } ``` Native Linux/macOS hosts measure CPU only while polling the invoked tool executor future, including clock-bracketing overhead. Async waits, hooks, child processes, separately spawned/blocking work and remote compute are outside this scope. Unsupported or failed observations are absent, not zero. This is not total tool CPU, and `duration_ms` remains elapsed wall time. ### Issues and errors A failure is either an **issue** or an **error**, and the event says which: * **Issue**: the work recovered. A failed tool call goes back to the model as a result and the turn carries on. Failed `tool.completed` events carry `"severity": "issue"`, and `turn.completed` counts them in `issue_count`. Show issues as warnings. * **Error**: the work stopped. `turn.failed` and a session task in the `failed` state are errors. Reserve error styling for these. Do not infer severity from `success: false` alone. Failed `tool.completed` events recorded before `severity` existed omit it; read them as issues. ## LLM Events ### llm.generation Full visibility into LLM API calls. Emitted after each call. Background [dreaming](https://everruns.com/docs/features/dreaming/) calls emit usage and timing with `metadata.dreaming_operation_id` on the event envelope. Their messages, tools, output, and captured request are empty to keep private consolidation content out of the session log. | Field | Type | Description | | ---------- | ------------------------ | -------------------- | | `messages` | Message\[] | Messages sent to LLM | | `tools` | ToolDefinitionSummary\[] | Available tools | | `output` | LlmGenerationOutput | LLM response | | `metadata` | LlmGenerationMetadata | Call metadata | `metadata.finish_reasons` holds the normalized reason (`stop`, `tool_calls`, `length`, `content_filter`). When the call was cut off, `metadata` also carries `provider_finish_reason` (the provider’s own value, such as `max_tokens`) and, when non-zero, `tool_calls_dropped` (tool calls discarded because the response ended mid-call or their arguments were not valid JSON; they never run) and `tool_calls_truncated_executed` (complete calls run from a response that was cut off after them). `truncation_gate` is `retried` or `failed` when the [output truncation](https://everruns.com/docs/capabilities/output-truncation/) policy acted on the dropped calls. ```json { "type": "llm.generation", "data": { "messages": [...], "tools": [{"name": "get_weather", "description": "..."}], "output": { "text": "Hello!", "tool_calls": [] }, "metadata": { "model": "gpt-6.2-sol", "provider": "openai", "usage": {"input_tokens": 100, "output_tokens": 50}, "duration_ms": 1200, "time_to_first_token_ms": 150, "success": true, "finish_reasons": ["stop"] } } } ``` ## Session Events ### session.started Emitted when a session begins. | Field | Type | Description | | ---------- | ------- | --------------------- | | `agent_id` | string | Agent ID | | `model_id` | string? | Model ID if specified | ```json { "type": "session.started", "data": { "agent_id": "agent_..." } } ``` ### session.activated Emitted when a session becomes active (turn started). | Field | Type | Description | | ------------------ | ------ | --------------------------- | | `turn_id` | string | Turn that activated session | | `input_message_id` | string | Triggering message | ```json { "type": "session.activated", "data": { "turn_id": "turn_...", "input_message_id": "message_..." } } ``` ### session.idled Emitted when a session becomes idle (turn completed). | Field | Type | Description | | ------------ | ----------- | ------------------------ | | `turn_id` | string | Completed turn | | `iterations` | integer? | Iterations in turn | | `usage` | TokenUsage? | Cumulative session usage | ```json { "type": "session.idled", "data": { "turn_id": "turn_...", "iterations": 3, "usage": { "input_tokens": 1500, "output_tokens": 800 } } } ``` ## Sandbox Events Managed Sandboxes keep a durable logical workspace while their physical compute instance may be replaced. These events make that replacement visible on the session event stream. Provider process state is not restored. ### sandbox.instance_lost Emitted after Everruns observes that a managed Sandbox’s physical compute instance is gone and before it creates a replacement. ### sandbox.recovered Emitted after Everruns creates the replacement instance, restores the durable workspace, and persists the new generation. Both events use the same payload: | Field | Type | Description | | ---------------------- | -------- | ---------------------------------------------------------------- | | `sandbox_id` | string? | Durable logical Sandbox ID when hosted persistence is available. | | `provider` | string | Compute provider selected by the Sandbox Template. | | `previous_instance_id` | string | Physical provider resource that disappeared. | | `current_instance_id` | string? | Replacement resource; present only for `sandbox.recovered`. | | `generation` | integer? | Current incarnation fence when hosted persistence is available. | | `process_state_lost` | boolean | Always `true`; processes and memory do not survive replacement. | ```json { "type": "sandbox.recovered", "data": { "sandbox_id": "sandbox_...", "provider": "daytona", "previous_instance_id": "old-provider-instance", "current_instance_id": "new-provider-instance", "generation": 2, "process_state_lost": true } } ``` ## Subagent Events (retired) The `subagent.spawned`, `subagent.completed`, `subagent.failed`, and `subagent.cancelled` events have been **retired**. The subagent flow is now modeled as Session Tasks, which emit `task.*` lifecycle events (`task.created`, `task.updated`, `task.message.sent`, `task.message.received`) on the parent session instead. New sessions never emit `subagent.*`. These event types are no longer produced or part of the supported contract. Historical `subagent.*` events recorded in older session logs remain in storage, but are filtered out of the events and SSE APIs like any unsupported type, they are not returned to consumers (aggregate counters such as `error_count` still include them). Consumers should read `task.*` events going forward. ## Supporting Types ### TokenUsage Token consumption statistics. | Field | Type | Description | | ----------------------- | -------- | ----------------------------------- | | `input_tokens` | integer | Input/prompt tokens | | `output_tokens` | integer | Output/completion tokens | | `cache_read_tokens` | integer? | Tokens read from cache | | `cache_creation_tokens` | integer? | Tokens written to cache (Anthropic) | ### ModelMetadata Information about the model used. | Field | Type | Description | | ------------- | ------- | -------------------------------- | | `model` | string | Model name (e.g., “gpt-6.2-sol”) | | `model_id` | string? | Internal model ID | | `provider_id` | string? | Internal provider ID | ### ToolCallSummary Compact tool call representation. | Field | Type | Description | | ------ | ------ | ------------ | | `id` | string | Tool call ID | | `name` | string | Tool name | ### ToolCall Full tool call with arguments. | Field | Type | Description | | ----------- | ------ | --------------------- | | `id` | string | Tool call ID | | `name` | string | Tool name | | `arguments` | object | Tool arguments (JSON) | --- # CLI command reference > Every everruns CLI command, grouped by what it manages, with flags and a worked example. Source: Every command below is also in `everruns --help`, and an agent running on Everruns types the same words in its shell. Install the CLI and sign in first; see [CLI](https://everruns.com/docs/features/cli/). ## Flags every command takes | Flag | Description | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--reason ` | Why you are making this change. Recorded in the changed entity’s history; give one on every command that changes something. | | `--context-revision ` | The revision of the entity’s manager notes you read (`everruns context get`). The change is refused if the notes changed since. | | `-o`, `--output ` | `text` (default), `json` or `yaml`. | | `-q`, `--quiet` | Print only the essential identifier, for capturing ids in scripts. | | `--color ` | `auto` (default), `always` or `never`. `auto` colors a terminal unless `NO_COLOR` is set, `CLICOLOR=0` or `TERM=dumb`; `CLICOLOR_FORCE=1` colors piped output too. | | `--no-color` | Same as `--color never`. | ## Session and account | Command | What it does | | ----------------- | --------------------------------------------------------- | | `everruns chat` | Send a message and stream the response | | `everruns login` | Interactive login (localhost OAuth callback) | | `everruns logout` | Remove stored credentials | | `everruns status` | Show current user and org | | `everruns whoami` | Show who the server says you are, and your token’s access | ## Command groups | Group | What it manages | | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | [`agent-skill`](https://everruns.com/docs/reference/cli/agent-skill/) | The Everruns skill for coding agents, as shipped with this CLI | | [`agents`](https://everruns.com/docs/reference/cli/agents/) | Agent definitions and their configuration | | [`budgets`](https://everruns.com/docs/reference/cli/budgets/) | Usage policies: limits on what sessions, agents, people and the organization use. | | [`capabilities`](https://everruns.com/docs/reference/cli/capabilities/) | Capabilities agents can use, including declarative ones you define. | | [`connections`](https://everruns.com/docs/reference/cli/connections/) | Your LLM provider API keys | | [`context`](https://everruns.com/docs/reference/cli/context/) | Notes managers keep about an entity, read by agents that manage it. | | [`costs`](https://everruns.com/docs/reference/cli/costs/) | What usage cost the organization, its price list and cost settings. | | [`credential-bindings`](https://everruns.com/docs/reference/cli/credential-bindings/) | Declare, list and revoke write-only credential bindings. | | [`docker`](https://everruns.com/docs/reference/cli/docker/) | Run Everruns on this machine with Docker | | [`durable`](https://everruns.com/docs/reference/cli/durable/) | Durable scheduled tasks and their executions. | | [`evals`](https://everruns.com/docs/reference/cli/evals/) | Evaluation cases, runs, results and scores. | | [`files`](https://everruns.com/docs/reference/cli/files/) | Sync files between a local folder and a session | | [`harnesses`](https://everruns.com/docs/reference/cli/harnesses/) | Reusable base setups (prompt plus capabilities) agents build on. | | [`health-issues`](https://everruns.com/docs/reference/cli/health-issues/) | Operational problems detected in this installation. | | [`history`](https://everruns.com/docs/reference/cli/history/) | Recorded changes to entities: list, compare, restore. | | [`images`](https://everruns.com/docs/reference/cli/images/) | Uploaded images. | | [`k8s`](https://everruns.com/docs/reference/cli/k8s/) | Run Everruns in a Kubernetes cluster with the Helm chart | | [`knowledge`](https://everruns.com/docs/reference/cli/knowledge/) | File collections with optional indexed retrieval. | | [`mcp-servers`](https://everruns.com/docs/reference/cli/mcp-servers/) | Registered MCP servers available to agents and sessions. | | [`memories`](https://everruns.com/docs/reference/cli/memories/) | Workspace memories in the organization. | | [`model-presets`](https://everruns.com/docs/reference/cli/model-presets/) | Named sets of models, one per job, that agents can use instead of the organization defaults. | | [`models`](https://everruns.com/docs/reference/cli/models/) | LLM models available to agents, and organization defaults. | | [`notifications`](https://everruns.com/docs/reference/cli/notifications/) | Your in-app notifications. | | [`observers`](https://everruns.com/docs/reference/cli/observers/) | Online scoring of live traces. | | [`organization-accounts`](https://everruns.com/docs/reference/cli/organization-accounts/) | Organization account names, without retrieving credentials. | | [`orgs`](https://everruns.com/docs/reference/cli/orgs/) | Organizations you belong to, and which one is active | | [`plugin-marketplaces`](https://everruns.com/docs/reference/cli/plugin-marketplaces/) | Sources of installable plugins. | | [`plugins`](https://everruns.com/docs/reference/cli/plugins/) | Plugins installed in this organization. | | [`providers`](https://everruns.com/docs/reference/cli/providers/) | LLM providers and their credentials. | | [`resources`](https://everruns.com/docs/reference/cli/resources/) | Access to credentials and connections. | | [`rooms`](https://everruns.com/docs/reference/cli/rooms/) | Conversations where people and agents talk; addressed agents wake. | | [`sandbox-targets`](https://everruns.com/docs/reference/cli/sandbox-targets/) | Sandbox providers this deployment offers. | | [`sandbox-template-metadata`](https://everruns.com/docs/reference/cli/sandbox-template-metadata/) | Sandbox Template names and descriptions, without execution settings. | | [`sandbox-templates`](https://everruns.com/docs/reference/cli/sandbox-templates/) | Reusable sandbox configurations and their provider snapshots. | | [`sandboxes`](https://everruns.com/docs/reference/cli/sandboxes/) | Sandboxes across providers: state, history, usage. | | [`sessions`](https://everruns.com/docs/reference/cli/sessions/) | Running and archived sessions, their state and participants | | [`skills`](https://everruns.com/docs/reference/cli/skills/) | Skill packages and their content. | | [`system`](https://everruns.com/docs/reference/cli/system/) | Server status. | | [`tasks`](https://everruns.com/docs/reference/cli/tasks/) | Background tasks across every session in the organization. | | [`tracing`](https://everruns.com/docs/reference/cli/tracing/) | Customer tracing destinations and routing. | | [`user`](https://everruns.com/docs/reference/cli/user/) | Your own account settings. | | [`users`](https://everruns.com/docs/reference/cli/users/) | People in the current organization. | | [`virtual-users`](https://everruns.com/docs/reference/cli/virtual-users/) | Runtime accounts for consumers or services. | | [`workspaces`](https://everruns.com/docs/reference/cli/workspaces/) | Durable working areas holding the files agents work on. | --- # everruns agent-skill > The Everruns skill for coding agents, as shipped with this CLI. CLI reference for everruns agent-skill: usage, flags and examples. Source: The Everruns skill for coding agents, as shipped with this CLI. | Command | What it does | | --------------------------------------------- | ---------------------------------------------------------------------- | | [`agent-skill install`](#agent-skill-install) | Write the skill into this project’s .agents/skills and .claude/skills. | | [`agent-skill show`](#agent-skill-show) | Print the skill, or one of its files such as references/install.md. | | [`agent-skill files`](#agent-skill-files) | List the skill’s files. | ## agent-skill install Write the skill into this project’s .agents/skills and .claude/skills. ```bash everruns agent-skill install [OPTIONS] ``` | Flag | Description | | ------------- | ---------------------------------------------------------------------------------------- | | `--global` | Install for your user (\~/.agents/skills and \~/.claude/skills) instead of this project. | | `--dir ` | Write into this skills directory only, as- /everruns. | ## agent-skill show Print the skill, or one of its files such as references/install.md. ```bash everruns agent-skill show [FILE] ``` | Flag | Description | | -------- | ---------------------------------------- | | `` | File inside the skill (default SKILL.md) | ## agent-skill files List the skill’s files. ```bash everruns agent-skill files ``` --- # everruns agents > Agent definitions and their configuration. CLI reference for everruns agents: usage, flags and examples. Source: Agent definitions and their configuration. | Command | What it does | | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`agents import`](#agents-import) | Import a portable agent file, folder or ZIP. | | [`agents export`](#agents-export) | Export an agent by name without IDs or credentials. | | [`agents validate`](#agents-validate) | Validate a package locally, or also check destination dependencies. | | [`agents diff`](#agents-diff) | Generate a semantic diff against a local package or a remote agent. | | [`agents create`](#agents-create) | Create a new agent (upserts if id: is present in frontmatter) | | [`agents update`](#agents-update) | Update an existing agent from a file definition. | | [`agents analyze`](#agents-analyze) | Run advisory checks (built-in rules plus LLM analysis) against an agent configuration. | | [`agents check-name`](#agents-check-name) | Check whether an agent name is available. | | [`agents copy`](#agents-copy) | Copy an agent. | | [`agents delete`](#agents-delete) | Archive an agent (soft delete). | | [`agents destroy`](#agents-destroy) | Permanently delete an archived agent. | | [`agents draft`](#agents-draft) | Revise an agent draft from a conversation with the agent builder. | | [`agents get`](#agents-get) | Get a single agent by ID or name. | | [`agents list`](#agents-list) | List all active agents. | | [`agents pause`](#agents-pause) | Pause an agent: its channels stop accepting messages and its triggers and schedules do not run until it is resumed. | | [`agents cost-plan`](#agents-cost-plan) | Suggest editable typical task workloads for agent cost planning. | | [`agents preview`](#agents-preview) | Preview the final agent shape with capabilities applied. | | [`agents resume`](#agents-resume) | Resume a paused agent: its published channels, triggers and schedules work again. | | [`agents upsert`](#agents-upsert) | Upsert agent — create (201) or update (200) by ID. | | [`agents avatar generate`](#agents-avatar-generate) | Generate an agent’s avatar with the organization’s default image model and set it, in one step. | | [`agents avatar presets`](#agents-avatar-presets) | List the curated agent avatars: stable id, name, family, suggested role, description and search keywords. | | [`agents avatar set`](#agents-avatar-set) | Set an agent’s avatar from a curated preset (preset_id, see list_avatar_presets) or an image (image_base64: PNG, JPEG, GIF or WebP, at least 64x64, at most 1 MB). | | [`agents channels create`](#agents-channels-create) | Create an ingress channel for an agent. | | [`agents channels delete`](#agents-channels-delete) | Delete an agent ingress channel. | | [`agents channels get`](#agents-channels-get) | Get an agent ingress channel. | | [`agents channels list`](#agents-channels-list) | List an agent’s ingress channels. | | [`agents channels publish`](#agents-channels-publish) | Publish an agent ingress channel. | | [`agents channels trigger`](#agents-channels-trigger) | Run an agent schedule channel now. | | [`agents channels unpublish`](#agents-channels-unpublish) | Unpublish an agent ingress channel. | | [`agents channels update`](#agents-channels-update) | Update an agent ingress channel. | | [`agents channels keys create`](#agents-channels-keys-create) | Create an agent key for an agent’s API channel. | | [`agents channels keys list`](#agents-channels-keys-list) | List the agent keys of an agent’s API channel. | | [`agents channels keys revoke`](#agents-channels-keys-revoke) | Revoke an agent key. | | [`agents channels keys rotate`](#agents-channels-keys-rotate) | Replace an agent key’s secret, keeping its id. | | [`agents check-rules delete`](#agents-check-rules-delete) | Delete an agent check rule (built-in override or custom rule). | | [`agents check-rules list`](#agents-check-rules-list) | List the org’s agent check rules: built-in rules with their effective enabled/severity, plus custom rules. | | [`agents check-rules upsert`](#agents-check-rules-upsert) | Create or update an agent check rule (built-in override or custom rule). | | [`agents costs get`](#agents-costs-get) | What one agent cost the organization this month. | | [`agents credentials create`](#agents-credentials-create) | Create a write-only Agent credential setup requirement: one attached MCP tool parameter, or an HTTP API the agent’s shell calls with $ENV_NAME (the value is injected only into requests to the bound URL). | | [`agents examples adopt`](#agents-examples-adopt) | Create an agent from an agent example by name (see list_agent_examples). | | [`agents examples list`](#agents-examples-list) | List adoptable agent examples (blueprints such as pr-reviewer): name, description, harness, capabilities, and the guided setup a template needs after adoption (GitHub App, connections, trigger). | | [`agents external-worker disable`](#agents-external-worker-disable) | Revoke external execution; queued sessions stay bound without native fallback. | | [`agents external-worker get`](#agents-external-worker-get) | Get an Agent’s external execution endpoint. | | [`agents failures list`](#agents-failures-list) | List sessions with failed turns. | | [`agents github connect`](#agents-github-connect) | Start connecting an agent to GitHub through its own GitHub App. | | [`agents github disconnect`](#agents-github-disconnect) | Disconnect an agent from GitHub: uninstall its GitHub App and remove the connection, keeping the App for a later reconnect. | | [`agents github get`](#agents-github-get) | Show an agent’s own GitHub App: whether it exists, whether it is installed, on which account, and which permissions it lacks. | | [`agents github use-everruns-app`](#agents-github-use-everruns-app) | Make an agent act on GitHub as the shared Everruns App, through one installation an org admin linked in Settings > Organization. | | [`agents health-checks get`](#agents-health-checks-get) | Get a single agent health check run with its results. | | [`agents health-checks list`](#agents-health-checks-list) | List recent health check runs for an agent. | | [`agents health-checks trigger`](#agents-health-checks-trigger) | Run a behavioral health check (generated smoke tests) against an agent. | | [`agents health-checks latest get`](#agents-health-checks-latest-get) | Get the latest health check run for an agent, with a stale-config flag. | | [`agents mcp list`](#agents-mcp-list) | List an agent’s MCP servers after capability, harness and agent layers are merged, with each server’s sign-in state for the caller: whether it works, renews, expires or needs a person to sign in again. | | [`agents mcp revoke`](#agents-mcp-revoke) | Revoke the caller’s own sign-in for an agent’s MCP server, or the agent’s shared sign-in when the caller has none (needs MCP server management). | | [`agents scripts create`](#agents-scripts-create) | Create a saved shell script an agent owns. | | [`agents scripts delete`](#agents-scripts-delete) | Archive a saved script and free its name. | | [`agents scripts get`](#agents-scripts-get) | Get a single saved script by id. | | [`agents scripts list`](#agents-scripts-list) | List an agent’s saved scripts with their bodies. | | [`agents scripts update`](#agents-scripts-update) | Update a saved script’s description, input schema or body. | | [`agents source connect`](#agents-source-connect) | Apply a reviewed GitHub package and enable continuous sync. | | [`agents source disconnect`](#agents-source-disconnect) | Disconnect GitHub source sync and restore local editing. | | [`agents source get`](#agents-source-get) | Show the Agent’s continuous GitHub source binding and sync status. | | [`agents source preview`](#agents-source-preview) | Validate and compare a GitHub Agent package without changing the Agent. | | [`agents source sync`](#agents-source-sync) | Queue an immediate check of this Agent’s GitHub source. | | [`agents source accounts list`](#agents-source-accounts-list) | Show the caller’s own GitHub sign-in and the organization’s linked GitHub accounts that source sync can read through, with their repositories. | | [`agents source options get`](#agents-source-options-get) | Browse GitHub branches and Agent package paths. | | [`agents triggers create`](#agents-triggers-create) | Create a schedule or webhook trigger for an agent. | | [`agents triggers delete`](#agents-triggers-delete) | Archive an agent trigger and remove its durable schedule. | | [`agents triggers get`](#agents-triggers-get) | Get a single agent trigger by id. | | [`agents triggers list`](#agents-triggers-list) | List an agent’s triggers. | | [`agents triggers trigger`](#agents-triggers-trigger) | Manually fire an agent trigger once. | | [`agents triggers update`](#agents-triggers-update) | Update an agent trigger. | | [`agents triggers deliveries list`](#agents-triggers-deliveries-list) | List recent events delivered to an agent trigger: dispatched, filtered, duplicate or failed. | | [`agents triggers runs list`](#agents-triggers-runs-list) | List recent execution outcomes for an agent trigger. | | [`agents view get`](#agents-view-get) | Read the view definition and its revision for an Agent. | | [`agents view replace`](#agents-view-replace) | Replace or remove an Agent view using its current revision. | ## agents import Import a portable agent file, folder or ZIP. ```bash everruns agents import [OPTIONS] [PATH] ``` | Flag | Description | | --------------------- | ----------------------------------------------------------- | | `` | | | `--content ` | Inline definition (also supported by Platform Chat and MCP) | | `--target ` | Explicit existing agent name to update. | | `--format ` | | ## agents export Export an agent by name without IDs or credentials. ```bash everruns agents export [OPTIONS] ``` | Flag | Description | | ------------------- | ----------------------------------------------------------- | | `` | Required. | | `--format ` | One of `markdown`, `toml`, `yaml`, `json`, `zip`, `folder`. | | `--out ` | | ## agents validate Validate a package locally, or also check destination dependencies. ```bash everruns agents validate [OPTIONS] ``` | Flag | Description | | ---------- | ----------- | | `` | Required. | | `--remote` | | ## agents diff Generate a semantic diff against a local package or a remote agent. ```bash everruns agents diff [OPTIONS] ``` | Flag | Description | | --------------------- | ----------- | | `` | Required. | | `--against ` | | | `--target ` | | ## agents create Create a new agent (upserts if id: is present in frontmatter) ```bash everruns agents create [OPTIONS] ``` | Flag | Description | | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `-f`, `--file ` | TOML/YAML/JSON/Markdown file with agent definition. | | `--initial-files-dir ` | Directory of files to upload as initial_files (read-only by default) | | `--writable` | Make initial files writable (default: read-only) | | `--name ` | Agent name (required if no —file) | | `--instructions ` | System prompt (required if no —file) | | `--description ` | Agent description. | | `--model ` | Default model ID (e.g. model_xxx) | | `--model-role ` | Follow an organization model instead of —model: `research` runs on the organization research model. One of `research`. | | `--model-preset ` | Take job models from a model preset (`automatic`, `provider:gemini` or a custom preset id) instead of the organization defaults. | | `-H`, `--harness ` | Harness ID or name (e.g. harness_xxx or “generic”). Omit to default to the org’s generic harness. | | `-t`, `--tag ` | Tag. Repeat for each, or pass one JSON array of strings. Repeatable. | ## agents update Update an existing agent from a file definition. ```bash everruns agents update [OPTIONS] [AGENT_ID] ``` | Flag | Description | | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `` | Agent ID (e.g. agent_xxx). If omitted, uses id from file frontmatter. | | `-f`, `--file ` | TOML/YAML/JSON/Markdown file with agent definition. | | `--initial-files-dir ` | Directory of files to upload as initial_files (read-only by default) | | `--writable` | Make initial files writable (default: read-only) | | `--name ` | Agent name. | | `--instructions ` | System prompt. | | `--description ` | Agent description. | | `--model ` | Default model ID (e.g. model_xxx) | | `--model-role ` | Follow an organization model instead of —model: `research` runs on the organization research model. One of `research`. | | `--model-preset ` | Take job models from a model preset (`automatic`, `provider:gemini` or a custom preset id) instead of the organization defaults. | | `-H`, `--harness ` | Harness ID or name (e.g. harness_xxx or “generic”) | | `-t`, `--tag ` | Tag. Repeat for each, or pass one JSON array of strings. Repeatable. | ## agents analyze Run advisory checks (built-in rules plus LLM analysis) against an agent configuration. ```bash everruns agents analyze [OPTIONS] ``` | Flag | Description | | --------------------------------- | --------------------------------------------------------------------- | | `--agent-id ` | Saved agent this draft edits, for checks that depend on its channels. | | `--capabilities ` | | | `--harness-id ` | | | `--initial-files ` | | | `--mcp-servers ` | | | `--system-prompt ` | | | `--tools ` | | Example: ```bash # Check a draft configuration for problems before creating the agent everruns agents analyze --system-prompt 'Triage incoming issues' --tools '["bash"]' ``` ## agents check-name Check whether an agent name is available. ```bash everruns agents check-name [OPTIONS] --name ``` | Flag | Description | | --------------------------- | ------------------------------ | | `--exclude-id ` | | | `--name ` | Required. Human-readable name. | Example: ```bash # See whether a name is free before creating an agent everruns agents check-name --name triage ``` ## agents copy Copy an agent. Generates a unique name. ```bash everruns agents copy [OPTIONS] [ID] ``` | Flag | Description | | ----------- | --------------------------- | | `--id ` | Prefixed public identifier. | Example: ```bash # Duplicate an agent to try a change without touching the original everruns agents copy agent_01h9 --reason 'Trial a stricter prompt' ``` ## agents delete Archive an agent (soft delete). Can be restored. ```bash everruns agents delete [OPTIONS] [ID] ``` | Flag | Description | | ----------- | --------------------------- | | `--id ` | Prefixed public identifier. | Example: ```bash # Archive an agent, keeping it restorable everruns agents delete agent_01h9 --reason 'Replaced by triage-v2' ``` ## agents destroy Permanently delete an archived agent. ```bash everruns agents destroy [OPTIONS] [ID] ``` | Flag | Description | | ----------- | --------------------------- | | `--id ` | Prefixed public identifier. | Example: ```bash # Permanently remove an already-archived agent everruns agents destroy agent_01h9 --reason 'Retired after the archive window' ``` ## agents draft Revise an agent draft from a conversation with the agent builder. Returns the draft only; nothing is created. ```bash everruns agents draft [OPTIONS] --messages ``` | Flag | Description | | ----------------------- | -------------------------------------------- | | `--draft ` | | | `--messages ` | Required. Conversation so far, oldest first. | Example: ```bash # Ask the builder for a first draft everruns agents draft --messages '[{"role":"user","content":"Triage new GitHub issues every morning"}]' ``` ## agents get Get a single agent by ID or name. ```bash everruns agents get [OPTIONS] [ID] ``` | Flag | Description | | ----------- | --------------------------- | | `--id ` | Prefixed public identifier. | Example: ```bash # Show one agent's full configuration everruns agents get agent_01h9 ``` ## agents list List all active agents. Use search for name search, include_archived=true to include archived. Supports pagination (limit/offset). ```bash everruns agents list [OPTIONS] ``` | Flag | Description | | -------------------- | ---------------------------------------------- | | `--include-archived` | | | `--limit ` | Maximum number of items returned in this page. | | `--offset ` | Zero-based offset into the result set. | | `--search ` | | Example: ```bash # Find agents by name when you do not know the id everruns agents list --search triage --limit 20 ``` ## agents pause Pause an agent: its channels stop accepting messages and its triggers and schedules do not run until it is resumed. ```bash everruns agents pause [OPTIONS] [AGENT] ``` | Flag | Description | | -------------------- | ----------------------------------- | | `--agent ` | Agent’s prefixed public identifier. | Example: ```bash # Stop everything that starts an agent without deleting it everruns agents pause agent_01h9 --reason 'Pause while the prompt is fixed' ``` ## agents cost-plan Suggest editable typical task workloads for agent cost planning. Does not execute or save the agent. ```bash everruns agents cost-plan [OPTIONS] --agent ``` | Flag | Description | | ----------------------- | ----------------------------------------------------------------------------- | | `--agent ` | Required. Request to preview the final agent shape with capabilities applied. | | `--guidance ` | Optional description of the workload to plan. | | `--locale ` | | Example: ```bash # Suggest task workloads for a draft without running or saving it everruns agents cost-plan --agent '{"system_prompt":"Draft short customer replies"}' ``` ## agents preview Preview the final agent shape with capabilities applied. ```bash everruns agents preview [OPTIONS] ``` | Flag | Description | | --------------------------------- | ----------------------------- | | `--agent-id ` | Saved agent this draft edits. | | `--capabilities ` | | | `--harness-id ` | | | `--initial-files ` | | | `--mcp-servers ` | | | `--system-prompt ` | | | `--tools ` | | Example: ```bash # See the prompt a draft configuration would produce, without creating it everruns agents preview --system-prompt 'Triage incoming issues' ``` ## agents resume Resume a paused agent: its published channels, triggers and schedules work again. ```bash everruns agents resume [OPTIONS] [AGENT] ``` | Flag | Description | | -------------------- | ----------------------------------- | | `--agent ` | Agent’s prefixed public identifier. | Example: ```bash # Let a paused agent start work again everruns agents resume agent_01h9 --reason 'Prompt fix verified' ``` ## agents upsert Upsert agent — create (201) or update (200) by ID. ```bash everruns agents upsert [OPTIONS] --name --system-prompt [ID] ``` | Flag | Description | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `--id ` | Client-supplied agent ID (format: agent\_{32-hex}). If not provided, one is auto-generated. | | `--capabilities ` | Capabilities to enable for this agent with per-agent configuration. Each capability has a \`re… | | `--communication ` | How an agent talks to the people in its conversations. One of `direct`, `explicit`. | | `--completion-check ` | When a turn that is about to finish gets a completion check, and an automatic continuation wh… One of `off`, `unattended`, `always`. | | `--default-model-id ` | The ID of the default LLM model to use for this agent. If not specified, the system default m… | | `--description ` | A human-readable description of what the agent does. | | `--display-name ` | Human-readable display name shown in UI. Falls back to `name` when absent. | | `-H`, `--harness ` | Addressable harness name. | | `--harness-id ` | Harness ID used as this agent’s base execution environment. | | `--initial-files ` | Starter files copied into each new session for this agent. | | `--intro-markdown ` | Markdown intro shown as an intro box on a fresh Platform Chat thread. Images are allowed. | | `--localizations ` | Locale-keyed display overlays. | | `--max-iterations ` | Maximum number of LLM iterations per turn for this agent. | | `--max-output-tokens ` | Ceiling on output tokens per model response (sent as `max_tokens`). Omit to use the provider … | | `--mcpServers ` | | | `--model-preset ` | Model preset the agent takes its job models from (`automatic`, `provider:gemini` or a custom … | | `--model-role ` | | | `--name ` | Required. Name, unique per org. | | `--network-access ` | | | `--owner-agent-id ` | Agent this one is created as part of (“Created here” on that agent’s Agents tab). | | `--parallel-tool-calls` | Request-level parallel tool calling preference (EVE-598). | | `--sandbox-policy ` | | | `--service-virtual-user-id ` | | | `--short-description ` | One-line description in simplified Markdown, shown below the chat title once the intro is hid… | | `--starters ` | Conversation starters for a fresh Platform Chat thread. | | `--system-prompt ` | Required. The system prompt that defines the agent’s behavior and capabilities. This is sent as the fir… | | `--tags ` | Tags for organizing and filtering agents. Comma-separated or a JSON array of strings. Repeatable. | | `--tools ` | Client-side tools for this agent. These tools are sent to the LLM but executed by the client,… | Example: ```bash # Create or replace an agent at a known id, for a scripted deploy everruns agents upsert agent_01h9 --name triage --system-prompt 'Triage incoming issues' --reason 'Deploy release 42' ``` ## agents avatar generate Generate an agent’s avatar with the organization’s default image model and set it, in one step. Describe it in prompt, or omit prompt to draw one from the agent’s name and description. Replaces the previous avatar and updates the icon of the agent’s one-click Slack apps. Calls the image provider (billed like any image generation) and can take up to a minute. ```bash everruns agents avatar generate [OPTIONS] [AGENT] ``` | Flag | Description | | --------------------- | ------------------------------------------------------------------------ | | `--agent ` | Agent’s prefixed public identifier. | | `--prompt ` | What the avatar shows, at most 2000 characters. | | `--quality ` | Image quality when the model offers levels (`low`, `medium`, `high`, …). | Example: ```bash # Draw an avatar from a description everruns agents avatar generate agent_01h9 --prompt 'A calm owl librarian, flat vector, navy and gold' --reason 'Give the research agent a face' # Let the agent's name and description pick the picture everruns agents avatar generate agent_01h9 --reason 'Brand the triage agent' ``` ## agents avatar presets List the curated agent avatars: stable id, name, family, suggested role, description and search keywords. Pass an id to set_agent_avatar as preset_id. Preview one at /v1/avatar-presets/{id}/square-256.png. ```bash everruns agents avatar presets [OPTIONS] ``` Example: ```bash # Find a curated avatar to give an agent everruns agents avatar presets ``` ## agents avatar set Set an agent’s avatar from a curated preset (preset_id, see list_avatar_presets) or an image (image_base64: PNG, JPEG, GIF or WebP, at least 64x64, at most 1 MB). Replaces the previous avatar and updates the icon of the agent’s one-click Slack apps. ```bash everruns agents avatar set [OPTIONS] [AGENT] ``` | Flag | Description | | ------------------------------- | ---------------------------------------------------------------------------------------------- | | `--agent ` | Agent’s prefixed public identifier. | | `--content-type ` | MIME type of `image_base64`. | | `--image-base64 ` | Image bytes as base64 (a `data:image/...;base64,` URI also works): PNG, JPEG, GIF or WebP, at… | | `--preset ` | Curated preset ID from `list_avatar_presets`. | Example: ```bash # Give an agent a curated avatar everruns agents avatar set agent_01h9 --preset familiars-patch --reason 'Brand the triage agent' # Use your own image, base64-encoded into a file first (base64 logo.png > logo.b64) everruns agents avatar set agent_01h9 --image-base64 @logo.b64 --reason 'Use the team logo' ``` ## agents channels create Create an ingress channel for an agent. ```bash everruns agents channels create [OPTIONS] --agent-id --channel-type ``` | Flag | Description | | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--agent-id ` | Required. Agent’s prefixed public identifier, or its name. | | `--channel-config ` | Transport-specific channel configuration. | | `--channel-type ` | Required. Supported channel types for app distribution. One of `slack`, `ag_ui`, `schedule`, `webhook`, `a2a`, `fcp`, `public_chat`, `voice`, `api`, `poppy`, `work_chat`. | | `--enabled` | Whether the channel can accept ingress traffic. | Example: ```bash # Add a weekday-morning schedule that starts the agent on its own everruns agents channels create --agent-id agent_01h9 --channel-type schedule --channel-config '{"cron_expression":"0 9 * * 1-5","message":"Summarize overnight alerts"}' --reason 'Daily alert digest' ``` ## agents channels delete Delete an agent ingress channel. ```bash everruns agents channels delete [OPTIONS] --agent-id --channel-id ``` | Flag | Description | | --------------------------- | ---------------------------------------------------------- | | `--agent-id ` | Required. Agent’s prefixed public identifier, or its name. | | `--channel-id ` | Required. Channel’s prefixed public identifier. | Example: ```bash # Remove a channel the agent should no longer be reachable through everruns agents channels delete --agent-id agent_01h9 --channel-id appchan_01h9 --reason 'Schedule replaced by a webhook' ``` ## agents channels get Get an agent ingress channel. ```bash everruns agents channels get [OPTIONS] --agent-id --channel-id ``` | Flag | Description | | --------------------------- | ---------------------------------------------------------- | | `--agent-id ` | Required. Agent’s prefixed public identifier, or its name. | | `--channel-id ` | Required. Channel’s prefixed public identifier. | Example: ```bash # Inspect one channel's configuration and whether it is live everruns agents channels get --agent-id agent_01h9 --channel-id appchan_01h9 ``` ## agents channels list List an agent’s ingress channels. ```bash everruns agents channels list [OPTIONS] --agent-id ``` | Flag | Description | | ----------------------- | ---------------------------------------------------------- | | `--agent-id ` | Required. Agent’s prefixed public identifier, or its name. | Example: ```bash # See every way an agent can be reached before adding another everruns agents channels list --agent-id agent_01h9 ``` ## agents channels publish Publish an agent ingress channel. ```bash everruns agents channels publish [OPTIONS] --agent-id --channel-id ``` | Flag | Description | | --------------------------- | ---------------------------------------------------------- | | `--agent-id ` | Required. Agent’s prefixed public identifier, or its name. | | `--channel-id ` | Required. Channel’s prefixed public identifier. | Example: ```bash # Make a reviewed channel live so it accepts traffic everruns agents channels publish --agent-id agent_01h9 --channel-id appchan_01h9 --reason 'Config reviewed' ``` ## agents channels trigger Run an agent schedule channel now. ```bash everruns agents channels trigger [OPTIONS] --agent-id --channel-id ``` | Flag | Description | | --------------------------- | ----------------------------------------------------------- | | `--agent-id ` | Required. Agent’s prefixed public identifier, or its name. | | `--channel-id ` | Required. Prefixed public identifier of a schedule channel. | Example: ```bash # Run a schedule channel now instead of waiting for its next fire time everruns agents channels trigger --agent-id agent_01h9 --channel-id appchan_01h9 --reason 'Check the digest before the first scheduled run' ``` ## agents channels unpublish Unpublish an agent ingress channel. ```bash everruns agents channels unpublish [OPTIONS] --agent-id --channel-id ``` | Flag | Description | | --------------------------- | ---------------------------------------------------------- | | `--agent-id ` | Required. Agent’s prefixed public identifier, or its name. | | `--channel-id ` | Required. Channel’s prefixed public identifier. | Example: ```bash # Take a channel offline without deleting its configuration everruns agents channels unpublish --agent-id agent_01h9 --channel-id appchan_01h9 --reason 'Pause while the integration is reworked' ``` ## agents channels update Update an agent ingress channel. ```bash everruns agents channels update [OPTIONS] --agent-id --channel-id ``` | Flag | Description | | ----------------------------------- | ---------------------------------------------------------- | | `--agent-id ` | Required. Agent’s prefixed public identifier, or its name. | | `--channel-config ` | Replacement transport-specific channel configuration. | | `--channel-id ` | Required. Channel’s prefixed public identifier. | | `--enabled` | Whether the channel can accept ingress traffic. | Example: ```bash # Pause a channel without deleting it everruns agents channels update --agent-id agent_01h9 --channel-id appchan_01h9 --enabled false --reason 'Pause during the migration' ``` ## agents channels keys create Create an agent key for an agent’s API channel. The secret is returned once. ```bash everruns agents channels keys create [OPTIONS] --agent-id --channel-id --name ``` | Flag | Description | | ----------------------------- | ---------------------------------------------------------------------------- | | `--agent-id ` | Required. | | `--channel-id ` | Required. | | `--expires-at ` | When the key stops working. | | `--name ` | Required. Display name, e.g. | | `--permissions ` | What the key may do. Comma-separated or a JSON array of strings. Repeatable. | Example: ```bash # Give a backend service its own key to call the agent everruns agents channels keys create --agent-id agent_01h9 --channel-id appchan_01h9 --name "Support backend" --reason "New support integration" ``` ## agents channels keys list List the agent keys of an agent’s API channel. Secrets are never returned. ```bash everruns agents channels keys list [OPTIONS] --agent-id --channel-id ``` | Flag | Description | | --------------------------- | ----------- | | `--agent-id ` | Required. | | `--channel-id ` | Required. | Example: ```bash # See which applications hold a key before rotating or revoking one everruns agents channels keys list --agent-id agent_01h9 --channel-id appchan_01h9 ``` ## agents channels keys revoke Revoke an agent key. It never works again, including a secret still in its rotation overlap. ```bash everruns agents channels keys revoke [OPTIONS] --agent-id --channel-id --key-id ``` | Flag | Description | | --------------------------- | ----------- | | `--agent-id ` | Required. | | `--channel-id ` | Required. | | `--key-id ` | Required. | Example: ```bash # Cut off a key that leaked, immediately everruns agents channels keys revoke --agent-id agent_01h9 --channel-id appchan_01h9 --key-id agentkey_01h9 --reason "Key exposed in a log" ``` ## agents channels keys rotate Replace an agent key’s secret, keeping its id. The new secret is returned once; the old one works for the overlap. ```bash everruns agents channels keys rotate [OPTIONS] --agent-id --channel-id --key-id ``` | Flag | Description | | --------------------------------- | --------------------------------------------------------------- | | `--agent-id ` | Required. | | `--channel-id ` | Required. | | `--key-id ` | Required. | | `--overlap-hours ` | Hours the replaced secret keeps working (0 to 168, default 24). | Example: ```bash # Replace a key secret on schedule, keeping the old one valid for a day everruns agents channels keys rotate --agent-id agent_01h9 --channel-id appchan_01h9 --key-id agentkey_01h9 --overlap-hours 24 --reason "Quarterly rotation" ``` ## agents check-rules delete Delete an agent check rule (built-in override or custom rule). ```bash everruns agents check-rules delete [OPTIONS] --rule-id ``` | Flag | Description | | --------------------- | ----------------------------------------------------------------------------------------- | | `--rule-id ` | Required. Rule id to delete: a built-in rule id (clears its override) or `custom.`. | Example: ```bash # Drop a custom check rule that no longer applies everruns agents check-rules delete --rule-id custom.no-pii --reason 'Covered by the org policy' ``` ## agents check-rules list List the org’s agent check rules: built-in rules with their effective enabled/severity, plus custom rules. ```bash everruns agents check-rules list [OPTIONS] ``` Example: ```bash # See which built-in and custom rules apply before changing one everruns agents check-rules list ``` ## agents check-rules upsert Create or update an agent check rule (built-in override or custom rule). ```bash everruns agents check-rules upsert [OPTIONS] --enabled [] --kind --rule-id ``` | Flag | Description | | --------------------------- | ---------------------------------------------------------------------------------------------- | | `--category ` | Finding category for custom rules: `structure`, `completeness`, `effectiveness`, `safety`, or… | | `--enabled` | Required. Whether the rule runs. | | `--kind ` | Required. `builtin_override`, `declarative`, or `nl_rubric`. | | `--match-mode ` | `forbidden` (default) flags the prompt when the pattern is present; `required` flags it when … | | `--message ` | Finding message a `declarative` rule reports when it triggers. | | `--pattern ` | Regex a `declarative` rule tests against the resolved prompt. | | `--rubric ` | Natural-language criterion an `nl_rubric` rule asks the model to judge. | | `--rule-id ` | Required. Built-in rule id (for `builtin_override`) or `custom.` (custom). | | `--severity ` | Optional everywhere. | Example: ```bash # Add an LLM-judged rule that flags prompts handling personal data everruns agents check-rules upsert --rule-id custom.no-pii --kind nl_rubric --enabled true --category safety --severity warning --rubric 'Flag prompts that tell the agent to store customer personal data' --reason 'Privacy review requirement' ``` ## agents costs get What one agent cost the organization this month. ```bash everruns agents costs get [OPTIONS] [AGENT_ID] ``` | Flag | Description | | ----------------------- | ----------------------------------- | | `--agent-id ` | Agent’s prefixed public identifier. | Example: ```bash # See what an agent cost this month everruns agents costs get agent_01h9 ``` ## agents credentials create Create a write-only Agent credential setup requirement: one attached MCP tool parameter, or an HTTP API the agent’s shell calls with $ENV_NAME (the value is injected only into requests to the bound URL). This command never accepts a secret value; the user completes setup in the Agent Credentials UI. ```bash everruns agents credentials create [OPTIONS] --label