Configuration YAML

An agent is one YAML file in your repository. This page is the full schema reference: every field, its type, its default, and its constraints.

Config files live at agents/*.yaml by convention; .agents/, ellipsis/, and .ellipsis/ also work, including any subdirectory under them, with either a .yml or .yaml extension. The top-level ellipsis: block is what marks a file as an Ellipsis config: a YAML file in a config directory without one is treated as unrelated YAML and ignored. How files deploy, preview, and revive: Lifecycle.

Minimal config

Only the ellipsis: block is structurally required. Every other field has a default, so a file containing nothing else is a valid agent that runs on demand from the CLI, API, or dashboard. A useful agent adds instructions, a trigger, and repositories:

ellipsis:
  version: v1
  name: Unfilled shift digest

claude:
  system: |
    List next week's shifts in splitshift-api that are still
    unassigned and open a GitHub issue titled "Unfilled shifts
    next week" with the list, grouped by restaurant.

trigger:
  type: cron
  schedule: "0 9 * * 1"

sandbox:
  repositories:
    - name: splitshift-api

• ellipsis marks the file as an agent config and names it. version: v1 is the only supported schema version.
• claude.system is the agent's instructions. Omit it and the agent runs on Claude Code's own default prompt, like claude with no arguments.
• trigger decides when the agent runs on its own; Mondays at 09:00 UTC here. Omit it for a manual-only agent. All trigger shapes: Triggers.
• sandbox.repositories names the repositories cloned into the session's sandbox.

Merged to the default branch, this file is a live agent. Every Monday it wakes in a sandbox with splitshift-api checked out and opens the issue.

All fields

Types and defaults below come from the live validator. The schema is strict: an unknown or misplaced key (a top-level name: that belongs under ellipsis:, say) fails validation instead of being silently dropped.

Top-level shape:

ellipsis

The Ellipsis namespace: schema version, identity, organizational metadata, and the enabled/interactive/ide flags.

An agent config declares no kind. Setting ellipsis.kind: code_review makes the file a review pipeline with a different schema; writing kind: agent explicitly fails validation, so omit the key.

ellipsis.metadata:

claude

Allowed effort values, in increasing depth: low, medium, high, xhigh, max.

A settings file must not set environment keys that would redirect the model off the Ellipsis proxy (ANTHROPIC_*, ELLIPSIS_*, CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX, apiKeyHelper); use sandbox.variables for your own environment variables. A settings file that is missing, not a JSON object, over 64 KiB, or sets a protected key fails the session before the agent starts.

A system list composes the prompt from its parts in order, joined with blank lines:

claude:
  system:
    - file: .agents/prompts/engineering-standards.md
    - |
      Implement the Linear issue this session was started for. Open a
      pull request and link the issue in its description.

Referenced files are read at session start, at the commit the session has the config's repository checked out at, so prompt and code always move together. A file reference must not point at another agent config file.

codex

Run the agent on OpenAI's Codex CLI instead of Claude Code. Declaring the block at all is what selects the harness, so omit it unless you want Codex.

Codex has no equivalent of claude.effort, fallback_model, max_turns, or settings, and skills and mcp_servers are not wired through for this harness; setting one fails loudly rather than being ignored. The budget still bounds the session.

trigger

An agent declares at most one trigger, which decides when it runs on its own. A config with no trigger still runs on demand from the CLI, API, or dashboard. Behavior per surface: Triggers.

Cron trigger

A five-field expression cannot restrict both day-of-month and day-of-week; use * for one of them.

React trigger

Run the agent in response to a repository, issue, Sentry, or Slack event. A react trigger sets exactly one surface block; each block carries its own on: action list and filters.

Actions per surface:

Filter fields, each on the surfaces named above:

Mention trigger

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

One agent answers per platform. If two configs claim the same platform, the oldest one wins and the rest are ignored. With no claimant, the built-in Ellipsis responder answers.

sandbox

The machine the agent runs in. The environment model, caching, and testing workflow: Sandboxes.

skills

Claude Code skills installed for the session. Skills checked into a cloned repository's .claude/skills/ load automatically and need no entry here; a skills entry brings in skills the clones don't provide: another repository of your installation, a public repository, or a session with no repositories at all. See Skills.

At most 10 skills per config; each skill at most 50 files and 512 KiB total, 64 KiB per file, UTF-8 text only. A skill that cannot be resolved at session start fails the session before the agent starts.

structured_output

A JSON Schema contract for the session's output, passed to the runtime so the result is machine-readable.

budget

Spend caps for this agent, in US dollars. session caps a single session; day, week, and month cap the agent's own trailing spend. The full money model: Billing.

llm

Where this agent's completions go. Omit the block to use Ellipsis's own LLM proxy. To route one agent through a gateway of your own, register it on the Models page and name its id here; registering alone moves no traffic. See Custom LLM proxy.

mcp_servers

Built-in integrations this agent opts into by name, as a bare name or a {name: ...} object. Only consulted when the integration's account setting is "opt in only"; an integration left on "all sessions" is available to every agent regardless. Sessions spawned from an integration's own surface (a Slack mention, a Linear issue) always get that integration's tools without an entry here.

Validation

Every surface runs the same validator, so a file that validates in one place validates everywhere. Where an invalid config surfaces:

• On push to the default branch. A new file that fails validation is reported and no agent is created. An existing agent whose file becomes invalid keeps running its last valid version; the error shows on the agent in the dashboard, and you get an email the first time a working agent breaks.
• On pull requests. Ellipsis maintains one validation comment on the pull request listing every config file that fails to parse at the head commit, with the exact error per file. It updates on each push and confirms when everything parses.
• In the dashboard. The agent editor validates against the same validator before it opens the deploy pull request, so an invalid file never ships from there.
• At session start. Checks that need the session's own commit or your live account state run then, and a failure fails the session with the reason recorded on it: a system or settings file that is gone or over its limit, a skill that cannot be resolved, a stored variable with no value, a GitHub permission the installation was not granted, or an llm.proxy that no longer exists. See session exit statuses.

What fails, and where: