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.

  trigger                      session, in a fresh sandbox           artifact
──────────────────────────────────────────────────────────────────────────────────────
cron "0 9 * * 1"         ──▶  clones splitshift-web and        ──▶  the week's merged
                              splitshift-api, reads the             work, summarized
                              merged PRs, writes a summary          in Slack

@ellipsis on PR #482     ──▶  checks out the PR, runs the      ──▶  an answer in the
"why do the trade             failing test, reads the trace         PR thread
tests fail?"

Linear issue SPL-214     ──▶  reproduces the stuck trade,      ──▶  a pull request
"shift trade stuck            writes the fix and its test           against splitshift-api
in pending"

     every sandbox is destroyed when its session ends;
     the session's timeline, spend, and log persist

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

Anatomy of an agent

The complete file behind the first row of the diagram:

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

sandbox:
  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.