Agents as code

Ellipsis has no separate deploy system for agents. An agent is a YAML file in your repository, and the version on your default branch is the agent.

The model

Each agent is one file under agents/ in a repository Ellipsis is installed on. The file is the whole definition: what wakes the agent, which model it runs, its instructions, its environment, and what it may spend.

ellipsis:
  version: v1
  name: Recent work summary
  description: Summarizes the week's merged work across splitshift-web and splitshift-api

claude:
  model: claude-haiku-4-5-20251001
  system: |
    Summarize the pull requests merged in splitshift-web and
    splitshift-api over the last 7 days. Group them by theme,
    lead with user-facing changes, and return the summary as
    your answer.

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

sandbox:
  repositories:
    - name: splitshift-web
    - name: splitshift-api
  github:
    permissions: read_only

budget:
  session: 1.00

Merged to the default branch, this agent runs every Monday at 09:00 UTC, reads both repositories, and delivers its summary as the session result. Nothing else exists: no console-side copy of the config, no state that can drift from the file.

agents/ is the canonical directory; .agents/, ellipsis/, and .ellipsis/ work too, at any depth. A YAML file in those directories is an agent when it declares a top-level ellipsis: mapping; other YAML there is ignored. Every field the file can carry: Configuration YAML.

Deploy by merging

The default-branch version of the file is the live agent. Ellipsis syncs on every push to the default branch:

There is no deploy step and nothing to restart. A merged edit applies to the next session; a session already running keeps the config it started with, and every session records which version it ran (see Lifecycle).

An invalid config never takes an agent down: the last good version keeps running until you push a fix, and the error is recorded where the agent lives in the dashboard. Creating an agent from the dashboard follows the same path in reverse: Ellipsis opens a pull request adding the file, and the agent goes live when it merges.

Preview on a branch

Open a pull request that edits an agent file, and sessions triggered by that pull request run the branch's version of the config. You watch the edited agent behave on real events before merging; nothing is registered and no schedule changes. Previews apply on private repositories, for same-repo pull requests by authors with write access.

A pull request that breaks a config gets a comment from Ellipsis with the exact validation error, so a broken agent is caught in review, not after merge.

For agents a pull request will not trigger, such as the cron agent above, run the file directly:

$ agent session start --config-file agents/recent-work-summary.yaml --watch

The session runs the file as written, on its own, without touching the deployed agent.

Why git

Because agents are code, they inherit everything your code already has:

• Review before deploy. An agent change is a pull request: a teammate reads the new prompt and the new permissions before they go live.
• History. git log agents/recent-work-summary.yaml is the agent's changelog, with authors and reasons.
• Rollback. A bad change is git revert, and the previous version is live on merge.
• One source of truth. What is written is what runs. There is no console state to reconcile against the repository.

The directory itself becomes an artifact: ls agents/ reads like a team roster, one file per job the team has delegated. New teammates learn what is automated the same way they learn the codebase, by reading it.

Next: Cloud Agents for how a session executes, or the quick start to deploy your first file.