Agents as code

Each agent is one YAML file in your repository. Merging to the default branch deploys it; branches preview it; git gives you review, history, and rollback.

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 web-repo and api-repo

claude:
  model: claude-haiku-4-5-20251001
  system: |
    Summarize the pull requests merged in web-repo and
    api-repo 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"

permissions:
  github:
    permissions: read_only

environment:
  repositories:
    - name: web-repo
    - name: api-repo

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:

You push	Ellipsis does
A new `agents/name.yaml`	Registers the agent and starts any cron schedule.
An edit to the file	Updates the agent.
A rename or move (content unchanged)	Keeps the same agent: identity, history, and schedules carry over.
A delete	Removes the agent and its schedules. Past sessions stay intact.
An invalid edit	Records the error and keeps the last good version running.

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.

Agents without a file

An agent can also be created straight through the API, with no file in any repository. It is live as soon as the call returns, and you change it by calling the API again — useful for agents a script generates, or for trying one out before committing to it. The trade is everything in the list above: no review before deploy, no history, no rollback, no branch preview. If you want those, put the file in a repository.

Which mode an agent is in is reported as managed_by, and only one of them is editable through the API: a file-defined agent is refused, because the next push to its file would undo the change. Since an API-managed agent has no repository of its own, every file it references — a system prompt, a skill, a settings file — must name the repository that file lives in.

Moving an agent between the two

Neither mode is a dead end.

Link moves an API-managed agent into a repository. Ellipsis opens a pull request adding its config file; the agent keeps running unchanged while that sits, and merging hands it over to the file. Nothing happens if the pull request is never merged, and after it merges the agent is an ordinary file-defined agent — same id, same history, same sessions.

Unlink does the reverse: the file stops governing the agent, effective immediately, and further changes go through the API. The file is deliberately left in your repository, inert — Ellipsis stops reading it, and you delete it whenever you like.

So the usual path is to prototype an agent through the API and link it once it earns a place in the repository. Unlink is for the other direction: taking an agent under program control, or editing one whose repository you no longer want it tied to.

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