Agent config
Every field, default, and constraint in agent config YAML files.
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. 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.
For how agents deploy and sync, see Agents as code; for trigger behavior, the schedule, react, and mention guides; for spend, Budgets. This page documents the 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. |
claude | object | {} | Claude runtime config: the system prompt and model. Optional for mention-only agents. |
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. |
sandbox | object | {} | The sandbox the agent runs in: which repositories are checked out, which stored environment variables are injected, compute sizing, image customization, and lifecycle hooks. |
structured_output | object | null | null | JSON Schema contract for machine-readable run output. |
limits | object | all null | Per-run and trailing spend limits, in US dollars. |
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 still runs on demand from the CLI, API, or dashboard.
Cron trigger
Run the agent on a schedule. See Run agents on a schedule.
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 when repository, Linear, or Slack events happen. See React to repository events.
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 Answer @ellipsis mentions.
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 The sandbox for the environment and Bring secrets into a sandbox for variables.
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. |
image | object | {} | Customizes the container image. Ellipsis owns the base image (FROM, user, entrypoint, and preinstalled tooling); you contribute appended layers. |
image.dockerfile_append | string | null | null | RUN instructions appended onto the base image, e.g. installing a CLI. Only RUN is supported — FROM, USER, WORKDIR, ENTRYPOINT, and COPY are not. Changing it rebuilds and re-caches the image. |
hooks | object | {} | Shell scripts run at points in the sandbox lifecycle, each as the sandbox user with the sandbox variables available. A hook that exits non-zero fails the run before the agent starts. |
hooks.post_start | string | null | null | Runs after the container starts, before any repository is cloned. Use for repo-independent setup such as authenticating a CLI (e.g. doppler setup). Must not depend on repository contents. |
hooks.post_clone | string | null | null | Runs after all repositories are cloned and checked out, before the agent starts. Use for repo-dependent setup such as installing dependencies or code generation. |
compute | object | {} | Sandbox compute sizing. Every field is optional; an omitted field uses the platform default. A value outside the allowed range fails config validation, it is never clamped. Compute is billed on the requested allocation over the sandbox lifetime, so a bigger or longer sandbox costs proportionally more. |
compute.cpu | number | null | 1 | vCPU cores, 0.125 to 16. Fractional values are allowed (e.g. 0.5). |
compute.memory_mib | integer | null | 4096 | Memory in MiB, 512 to 65536 (64 GiB). |
compute.timeout_seconds | integer | null | 3600 | Maximum run wall clock in seconds, 60 to 86400 (24 hours). A run that reaches the timeout has its sandbox killed and fails. |
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. A lifecycle hook that exits non-zero fails the run.
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 defaults and 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 $50.00, which is also the platform maximum per-run budget. Config trailing ceilings are $1,000 / 1 day, $10,000 / 7 days, and $40,000 / 28 days.
Validation and sync behavior
| Case | Result |
|---|---|
File has no top-level ellipsis: block | Not an agent config: ignored entirely, even at a config path. |
ellipsis.version is unsupported | Validation fails. Only v1 exists. |
| YAML is empty | Rejected: an empty config has no claude.system. |
claude.system is empty on a non-mention agent | Validation fails. |
| Cron expression is invalid | Validation fails before anything is stored or scheduled. |
branches is set on a non-push react event | Validation fails. |
A sandbox.compute value is out of range | Validation fails; values are never clamped. Bounds: cpu 0.125 to 16, memory_mib 512 to 65536, timeout_seconds 60 to 86400. |
| New file is invalid | The sync reports the error and does not create an agent. |
| Existing file becomes invalid | The sync records the error and keeps the last good config. |
| File is removed | The agent is soft-deleted and its schedules removed. |