Config
Agent config YAML field reference.
This is the field-by-field reference for Ellipsis agent YAML files. The canonical path is agents/*.yaml; .agents/, ellipsis/, and .ellipsis/ are also accepted, including any subdirectory under them (for example .ellipsis/agents/*.yaml). The machine-readable source of truth is GET /agents/schema.
Every config file must declare a top-level ellipsis: mapping. Its presence is what identifies the file as an Ellipsis agent config: a .yaml/.yml file in a config directory without an ellipsis: block is treated as unrelated YAML and ignored (not synced, validated, or commented on).
For how agents are deployed and synced from GitHub, see Deploy. For how triggers behave, see Triggers; for the sandbox, see Sandbox; for spend, see Budgets. This page documents the YAML fields.
Top-level fields
The shape of an agent file. Every field has a default; a useful agent sets `triggers` and a `claude.system` prompt (mention agents need neither).
| Field | Type | Default | Description |
|---|---|---|---|
ellipsis | object | required | Ellipsis namespace: schema version, name/description, and organizational metadata. Its presence marks the file as an agent config. |
enabled | boolean | true | When false, cron, react, and mention starts are skipped. Manual runs still work. |
triggers | list of trigger objects | [] | How the agent runs automatically. Types: cron, react, mention. |
structured_output | object | null | null | JSON Schema contract for machine-readable run output. |
sandbox | object | {} | The sandbox the agent runs in: which repositories are checked out, which stored environment variables are injected, and compute sizing. |
limits | object | all null | Per-run and trailing spend limits, in US dollars. |
claude | object | {} | Claude runtime config: the system prompt and model. Optional for mention-only agents. |
ellipsis
The Ellipsis namespace: schema version, identity, and organizational metadata. Its presence is what marks a YAML file as an agent config; a config-path file without it is ignored.
| Field | Type | Default | Description |
|---|---|---|---|
version | string | v1 | Config schema version. Bumped only on a breaking shape change; an unsupported value fails validation. v1 is the only supported version today. |
name | string | null | null | Display name. Dashboard-created files slug this into the file path. |
description | string | null | null | Short summary shown in product surfaces. |
metadata | object | {} | Freeform labels and annotations. Does not affect how the agent runs; excluded from the config content identity. |
ellipsis.metadata
Freeform organization, modeled on Kubernetes labels and annotations. It has no effect on how the agent runs and is excluded from the config content identity.
| Field | Type | Default | Description |
|---|---|---|---|
labels | list of strings | [] | Flat string tags for grouping and filtering. |
annotations | object | {} | Arbitrary key-value pairs. |
claude
| Field | Type | Default | Description |
|---|---|---|---|
system | string | "" | The agent's instructions. Required (non-empty) for cron, react, and manual agents; ignored for mention agents, whose reply is built from the conversation. |
model | string | current default agent model | Model passed to Claude Code. Omit unless Ellipsis gave your account explicit guidance. |
triggers
An agent can declare zero or more triggers; each independently decides when the agent runs. A config with no triggers can still be run manually or through the API. See Triggers for how each type behaves; the fields are below.
Cron trigger
Run the agent on a schedule. See Triggers → Cron.
Run the agent on a schedule.
| Field | Type | Default | Description |
|---|---|---|---|
type | "cron" | required | Selects the cron trigger shape. |
schedule | string | required | Five-field cron, or an EventBridge cron(...), rate(...), or at(...) expression. Five-field cron is converted to EventBridge format. |
EventBridge Scheduler cannot restrict both day-of-month and day-of-week in one expression.
React trigger
Run the agent in response to repository and issue events. See Triggers → React.
Run the agent in response to repository and issue events.
| Field | Type | Default | Description |
|---|---|---|---|
type | "react" | required | Selects the react trigger shape. |
events | list of react event objects | required | Events that can start the agent. |
event | react event enum | required | The GitHub or Linear event to react to. |
repository | string | null | null | Repository name filter for the event. |
branches | list of strings | [] | Only valid for event: push. Exact names, prefixes ending in *, or "default" for the repository default branch. Empty matches every branch. |
Allowed event values:
| Value | Fires for |
|---|---|
pull_request_open | PR opened or marked ready for review. |
pull_request_open_draft | Draft PR opened. |
pull_request_merge | PR merged. |
pull_request_close | PR closed without merge. |
pull_request_push | Push to a branch with an open PR. |
pull_request_review_submitted | PR review submitted. |
pull_request_comment | Comment on a PR. |
issue_open | GitHub issue opened. |
issue_close | GitHub issue closed. |
issue_comment | Comment on a GitHub issue. |
linear_issue_open | Linear issue opened. |
push | Push to any branch of a GitHub repository. |
slack_channel_created | A new public channel created in your Slack workspace. |
Mention trigger
Route @ellipsis mentions to this agent instead of the built-in responder. See Triggers → Mention.
Route @ellipsis mentions to this agent instead of the built-in responder.
| Field | Type | Default | Description |
|---|---|---|---|
type | "mention" | required | Selects the mention trigger shape. |
platforms | list of platform strings | [] | Surfaces this agent answers @ellipsis on. Empty means all of them. |
Allowed platforms values:
| Value | Covers |
|---|---|
github | @ellipsis in GitHub PR and issue comments and reviews. |
slack | @ellipsis messages and app mentions in Slack. |
linear | @ellipsis in Linear issue comments. |
One agent answers per platform. If two configs claim the same platform the oldest one wins; the rest are ignored. With no claimant, the built-in Ellipsis responder answers.
sandbox
The sandbox the agent runs in. See Sandbox for how repositories and variables are resolved.
The sandbox the agent runs in. Each repository entry takes name (required), owner (defaults to the config account), and ref (defaults to the default-branch head).
| Field | Type | Default | Description |
|---|---|---|---|
repositories | list of repository objects | [] | Repositories checked out in the sandbox. Each takes name (required), owner, and ref. |
variables | list of variable objects | [] | Environment variables injected into the sandbox (an allowlist — only the variables named here reach this agent). Each entry takes a name and an optional value. |
variables[].name | string | required | The environment variable name. Must be a valid shell name (letters, digits, underscores; not starting with a digit). |
variables[].value | string | null | null | A literal value injected as-is — use for non-secret config like a log level or API base URL. Omit it to resolve the value by name from your sandbox-variables store (dashboard or PUT /sandboxes/variables) at run time, keeping secrets out of YAML. |
compute | object | {} | Reserved. No fields today. |
Ellipsis clones repositories available to the account installation, and can clone public repositories from other owners. It rejects private repositories outside the owning account. A variable with no value and no stored value fails the run, so define it before referencing it.
structured_output
| Field | Type | Default | Description |
|---|---|---|---|
type | "json_schema" | "json_schema" | Structured output type. |
json_schema | object | required | JSON Schema the agent output must satisfy. |
When present, Ellipsis passes this schema to the Claude Code runtime for the run's output.
limits
Per-run and trailing spend limits, in US dollars. See Budgets for account defaults and platform ceilings.
Spend limits, expressed in US dollars.
| Field | Type | Default | Description |
|---|---|---|---|
run | number | null | account default | Per-run budget for this agent. Clamped to the platform maximum. |
day | number | null | platform ceiling | Trailing one-day spend cap for this config. |
week | number | null | platform ceiling | Trailing seven-day spend cap for this config. |
month | number | null | platform ceiling | Trailing 28-day spend cap for this config. |
The account default run budget is $10.00 and the platform maximum per-run budget is $50.00. Config trailing ceilings are $50 / 1 day, $250 / 7 days, and $1,000 / 28 days.
Validation and sync behavior
| Case | Result |
|---|---|
File has no top-level ellipsis: block | Not treated as an agent config: ignored entirely (not synced, validated, or commented on), even at a config path. |
ellipsis.version is unsupported | Validation fails. |
| YAML is empty | Parses as a config with an empty claude.system, then validation rejects it for GitHub sync/API validation. |
claude.system is empty or whitespace | Validation fails. |
| Cron expression is invalid | Validation fails before the config is stored or scheduled. |
branches is set on a non-push react event | Validation fails. |
| New file is invalid | The sync reports an orphan error and does not create an agent. |
| Existing file becomes invalid | Ellipsis records the sync error and keeps the last good config. |
| File is removed | Ellipsis soft-deletes the saved config and syncs cron schedules. |