agent.yaml

An automation is one YAML file under agents/, .agents/, ellipsis/, or .ellipsis/ (any depth, .yml or .yaml); the top-level ellipsis: block is what marks a file as one, and a YAML file in those directories without it is ignored. The schema is strict: an unknown or misplaced key (a top-level name: that belongs under ellipsis:, say) fails validation instead of being dropped. What an automation is and how a file deploys: Automations.

# yaml-language-server: $schema=https://www.ellipsis.dev/schemas/latest/agent-config.json
ellipsis:
  version: v1
  name: recent-work-summary

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

claude:
  model: claude-haiku-4-5-20251001
  system: |
    Summarize the pull requests merged in the last week across the
    cloned repositories. Open a GitHub issue in web-repo titled
    "Weekly work summary" with the digest, grouped by repository.

environment: cloud_agent_environment

budget:
  session: 1.00

Every Monday at 09:00 UTC this opens one issue in web-repo and spends at most $1. The schema comment on line one gives you inline validation in any editor with a YAML language server.

Top-level fields

ellipsis

An automation declares no kind. ellipsis.kind: environment, slack, or code_review routes the file to a different schema; kind: agent fails validation, so omit the key. Whether a session accepts messages while it runs is a per-session request flag, not a field in this file.

claude

codex

Declaring codex: runs the automation on OpenAI's Codex CLI. It has no effort, fallback_model, max_turns, or settings, and skills and MCP servers are not wired through; setting one fails validation rather than being ignored.

trigger

At most one trigger, discriminated by type.

React surfaces, each a block under trigger: carrying its own on list and filters:

trigger:
  type: react
  pull_request:
    on: [opened, pushed]
    repositories: [web-repo, api-repo]
    base: [default]
    draft: false
    for:
      users: true
      bots: ["dependabot[bot]"]

permissions

The ellipsis map keys are resources: account, alerts, sessions, files, memories, reviews, configs, defaults, environments, secrets, templates, integrations, tokens. Each value is a level (read < write < delete, higher includes lower), a {level, match} grant, or a list of either; an unlisted resource is denied. match is a list of globs over the instance key and is only allowed on sessions, files, memories, secrets, and configs.

permissions:
  ellipsis:
    sessions: write
    files:
      - read
      - level: write
        match: ["reports/*"]
  github:
    permissions: read_only
    repositories: [web-repo]

environment

A string names a saved environment (its name, or its env_ id), substituted in at session start. An object defines the environment inline with the same six fields an environment file has: repositories, variables, compute, image, hooks, and mcp_servers. Field detail: Environments.

environment.mcp_servers

An entry is a built-in by bare name or {name}, or a custom server you define. Built-ins are linear and slack; a bare string with any other name fails validation, and a custom server may not reuse a built-in name or appear twice. A built-in entry only matters when that integration is set to opt-in inclusion; an integration left on all sessions is available regardless. GitHub is the gh CLI, always present, and takes no entry.

env and headers values may embed ${NAME} references, whole-value or inline (Bearer ${TOKEN}), resolved from your stored secrets at session start; a reference to a secret that does not exist fails the session.

skills

Skills under a cloned repository's .claude/skills/ load on their own; an entry here brings in a skill the clones do not provide. At most 10 per automation, each at most 50 files and 512 KiB, 64 KiB per file, UTF-8 only.

input

At least one of the two fields. json_schema is not allowed on a react automation, whose payload is the surface's own fields.

output

budget

All values in US dollars. session caps one session; day, week, and month cap this automation's own trailing spend over 1, 7, and 28 days. Account-wide limits: Organization.

Validation

Every path runs the same validator. When a commit to the default branch makes a file invalid, the automation keeps running its last good version and the error is recorded; the automation's page in the dashboard shows the message and the commit it came from. agent automation create -f agents/recent-work-summary.yaml sends the file to POST /v1/automations, which rejects an invalid definition with 400 and the same message. Referenced files (system[].file, settings.path, skills[].path) are checked again at session start at the session's own commit, and a missing one fails the session before the agent runs.