Cloud Agents

What cloud agents do

A cloud agent is one YAML file in your repository: a trigger, a model, and a prompt. When the trigger fires, Ellipsis creates a sandbox with your repositories cloned, the agent does the work, and it delivers a real artifact where your team already looks.

A cron trigger on "0 9 * * 1" clones splitshift-web and splitshift-api every Monday, reads the merged pull requests, and posts the week's work to Slack. An @ellipsis mention on PR #482 checks out the pull request, runs the failing trade test, and answers in the thread. A Linear issue reproduces the stuck shift trade, then opens a pull request against splitshift-api with the fix and its test.

Each of those is a session. Every sandbox is destroyed when its session ends, but the session outlives it: the full step timeline with each tool call's spend, the downloadable log, and the exact config version it ran (see Sessions). You pay per session. An agent with no trigger runs on demand from the dashboard, CLI, or API.

Anatomy of an agent

The complete file behind the weekly summary above:

ellipsis:
  version: v1
  name: Recent work summary          # how the agent appears everywhere

claude:
  model: claude-haiku-4-5-20251001   # per agent; default is claude-opus-5
  system: |                          # the instructions for every session
    Find the pull requests merged in splitshift-web and
    splitshift-api in the last 7 days and post a summary,
    under 150 words, to the #eng channel in Slack. Ground
    every line in a real PR. Never invent activity.

trigger:
  type: cron
  schedule: "0 9 * * 1"              # Mondays 09:00 UTC

environment:
  repositories:                      # cloned into the sandbox
    - name: splitshift-web
    - name: splitshift-api

budget:
  session: 1.00                      # a session may spend at most $1

Commit it as agents/recent-work-summary.yaml and merge: the version on your default branch is the live agent, with no deploy step (Agents as code). Every Monday at 09:00 UTC it starts a session, posts the summary to #eng, and shuts down; the session stays readable in the dashboard.

Four fields carry the definition. ellipsis.name is the agent's identity, trigger decides when it runs (Triggers), claude.model picks the model, and claude.system is the prompt it follows on every session. Everything else has a default; Configuration YAML covers every field.

Pages in this section

• Quick start: install the GitHub app, commit a starter agent, and watch its first session.
• Configuration YAML: every field, type, default, and how invalid configs fail.
• Triggers: cron, mentions, pull request, Sentry, Linear, and starts from the API and CLI.
• Lifecycle: deploy by merging, preview on a branch, disable, delete, and revive.
• Sessions: how a session executes, its statuses, the timeline, logs, and steering it live.
• Conversations: mention and on-demand sessions are durable; follow-ups keep full context.
• Sandboxes: the isolated machine per session, your image and tools, compute, IDE, and caching.
• Skills: teach every agent your team's conventions once, not per prompt.
• Permissions: scoped GitHub tokens, permission maps, read-only agents, and secrets.
• Guides: problem-shaped walkthroughs, from automating standups to diagnosing Sentry alerts.