Quick start

Three steps to a deployed agent: install the GitHub app, commit one YAML file, run it. The agent runs in the Ellipsis cloud, not on your machine.

Install the GitHub app

Go to app.ellipsis.dev/install, sign in with GitHub, and install the Ellipsis app on your account or organization. GitHub asks which repositories to grant; agents can only see the repositories you pick, and you can add more later from GitHub's app settings.

When the installation lands, the dashboard confirms it and offers your signup credit: $100 for organizations, $10 for personal accounts. Claim it; it funds your first sessions before usage-based billing starts.

That is the only setup. No runners, no tokens to mint, nothing to host.

Create your first agent

An agent is one YAML file in your repository. Any .yaml file under agents/ with a top-level ellipsis: block is an agent; the version on your default branch is the live one.

Create agents/recent-work-summary.yaml:

ellipsis:
  version: v1
  name: Recent work summary
  description: A weekly summary of the code changes we shipped

claude:
  model: claude-haiku-4-5-20251001
  system: |
    Use the GitHub tools to find the pull requests merged in the
    last week and summarize what the team has been working on.
    Keep it under 150 words and grounded in what the tools
    returned. Never invent activity.

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

sandbox:
  repositories:
    - name: <your-repo>

budget:
  session: 1.00
  week: 2.00

Five blocks carry the whole definition:

• ellipsis names the agent; the name is how it appears everywhere.
• claude.system is the instruction it follows on every session, and claude.model picks the model. GitHub tools are available automatically.
• trigger fires every Monday at 09:00 UTC (cron schedules run in UTC).
• sandbox.repositories lists the repositories cloned into the agent's sandbox. Substitute your repository name.
• budget is in US dollars: session caps one session, week caps the agent's trailing 7-day spend.

Commit it to your default branch:

git add agents/recent-work-summary.yaml
git commit -m "Add weekly work summary agent"
git push

Ellipsis syncs the file on push, registers the agent, and starts the cron schedule. It now appears on the dashboard's Agents page. (The dashboard offers the same flow in reverse: creating an agent there opens the pull request that adds this file.)

Run it

Run the first session now instead of waiting for Monday. In the dashboard, open Agents, select Recent work summary, and click Run agent. The dialog takes an optional prompt and budget; leave both empty. The session page shows every step as it happens: the sandbox starting, each tool call, and the result.

Or run it from the terminal. The agent CLI installs from Homebrew, and agent login authenticates through your browser:

brew install ellipsis-dev/cli/agent
agent login

Find the agent's id and start a session, streaming its steps with --watch:

$ agent config list
ID              SOURCE                                UPDATED           EDITED BY
agent_x9Kd3Fq2  agents/recent-work-summary.yaml@main  2026-07-31 16:02  <you>

$ agent session start --config agent_x9Kd3Fq2 --watch
✓ started session session_3Fp9dR2k
  https://app.ellipsis.dev/<your-account>?session=session_3Fp9dR2k
16:04:11  scheduled
Session starting…
Starting sandbox…
Fetching repositories…
Sandbox ready · <your-account>/<your-repo> · full build
16:04:52  running
Bash  (gh search prs --merged --json title,number,closedAt)
Bash  (gh pr view 412 --json title,body,files)
16:07:26  completed

✓ session session_3Fp9dR2k completed

The result reads like:

Merged 9 pull requests this week. The largest change: request
validation moved into its own middleware (#412, #418). Two bug
fixes in the billing flow (#425, #431), and the CI pipeline now
caches dependencies, cutting build times roughly in half (#436).

Every Monday after this, a session starts on its own.

What you built

A deployed agent, defined entirely by one file in git:

• The file on your default branch is the live agent. Edit the YAML and push, and the agent updates; delete the file and the agent is removed (Lifecycle).
• Every session runs in an isolated cloud sandbox and stays inspectable afterward: the step timeline, the spend, the log (Sessions).
• Budgets cap what it can cost, per session and over time.

From here:

• Configuration YAML: every field, type, and default.
• Triggers: mentions, pull request events, Sentry alerts, Linear issues, and starts from the API and CLI.
• Agents as code: why the file in git is the whole model.
• Guides: problem-shaped walkthroughs, from automating standups to diagnosing Sentry alerts.