Agent config

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).

Hover or tap any field in the blocks below to read its type, default, and description.

Complete example

ellipsis:
  version: v1
  name: Release note drafter
  description: Drafts release notes when release branches are pushed.
enabled: true
triggers:
  - type: react
    events:
      - event: push
        repository: app
        branches:
          - "release/*"
sandbox:
  repositories:
    - name: app
  variables:
    - name: LINEAR_API_KEY      # resolved from your sandbox-variables store
    - name: LOG_LEVEL
      value: info               # hardcoded inline
claude:
  system: |
    Review the commits in the push event.
    Draft release notes grouped by customer-visible feature, bug fix, and internal change.
    Open a pull request updating RELEASE_NOTES.md.
limits:
  run: 10
  day: 50
  week: 250
  month: 1000
structured_output:
  type: json_schema
  json_schema:
    type: object
    additionalProperties: false
    required:
      - summary
      - pull_request_url
    properties:
      summary:
        type: string
      pull_request_url:
        type: string

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).

ellipsis

objectrequired

Ellipsis namespace: schema version, name/description, and organizational metadata. Its presence marks the file as an agent config.

Hover or tap any block to see its field details.

`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.

version

stringdefault: v1

Config schema version. Bumped only on a breaking shape change; an unsupported value fails validation. v1 is the only supported version today.

Hover or tap any block to see its field details.

`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.

metadata:

labels

list of stringsdefault: []

Flat string tags for grouping and filtering.

Hover or tap any block to see its field details.

`claude`

claude:

system

stringdefault: ""

The agent's instructions. Required (non-empty) for cron, react, and manual agents; ignored for mention agents, whose reply is built from the conversation.

Hover or tap any block to see its field details.

`triggers`

An agent can declare zero or more triggers. Each one independently decides when the agent runs. A config with no triggers can still be run manually or through the API.

Cron trigger

Run the agent on a schedule.

triggers:

type

"cron"required

Selects the cron trigger shape.

Hover or tap any block to see its field details.

React trigger

Run the agent in response to repository and issue events.

triggers:

type

"react"required

Selects the react trigger shape.

Hover or tap any block to see its field details.

Mention trigger

A mention trigger routes @ellipsis mentions to this agent instead of the built-in responder. Use it to give your @ellipsis a custom system prompt, model, repositories, or tools.

Route @ellipsis mentions to this agent instead of the built-in responder.

triggers:

type

"mention"required

Selects the mention trigger shape.

Hover or tap any block to see its field details.

`sandbox`

The sandbox the agent runs in: which repositories are checked out, which environment variables are injected, and compute sizing. Each variables entry names a variable; with an inline value it is hardcoded (use for non-secret config), without one it is resolved by name from your sandbox-variables store at run time (so secrets stay out of the config file). Only the named variables reach the agent.

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).

sandbox:

repositories

list of repository objectsdefault: []

Repositories checked out in the sandbox. Each takes name (required), owner, and ref.

Hover or tap any block to see its field details.

`mcp_servers`

mcp_servers:

name

stringrequired

Server name. First-party servers are github, linear, and slack when those integrations are available.

Hover or tap any block to see its field details.

`tools`

tools:

type

stringrequired

Tool identifier.

Hover or tap any block to see its field details.

`structured_output`

structured_output:

type

"json_schema"default: "json_schema"

Structured output type.

Hover or tap any block to see its field details.

`limits`

Spend limits, expressed in US dollars.

limits:

run

number | nulldefault: account default

Per-run budget for this agent. Clamped to the platform maximum.

Hover or tap any block to see its field details.

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.

On this page