# Acyclic

> Acyclic runs a task as a swarm of coding agents, each in its own cloud sandbox, and merges their work into one patch. You drive it from the `acyclic` CLI, over MCP, or from the dashboard at https://acyclic.dev/dashboard.

This page is written for coding agents. Follow it top to bottom. Every command below is real, and `acyclic swarm <command> --help` has the full flags.

## 1. Install (once)

    curl -fsSL https://acyclic.dev/install.sh | sh     # prebuilt binary, checksum verified
    # or: npm install -g @acyclic-labs/cli
    acyclic --version                                  # `swarm answer` needs 0.0.7 or later

## 2. Sign in (once, needs a human)

    acyclic swarm login --site https://acyclic.dev --no-browser

This prints a URL and a code like `ABCD-EFGH`. **Stop and ask your human** to open the URL, sign in and approve the code. The command waits and exits 0 once they do. The session lasts 90 days.
- `acyclic swarm whoami` shows who you are signed in as.
- "not logged in" means no session in `swarm.json` next to the CLI config (default `~/.acyclic/swarm.json`).

## 3. Run a swarm on the current repository

    acyclic swarm run --task "Fix the failing tests in tests/" --dir . --watch

- `--dir .` uploads the working files: tracked and non-ignored files, with no `.git` history and no secrets (`.env*`, keys). Preview what goes up with `acyclic swarm run --dir . --dry-run`.
- `--repo https://github.com/owner/repo` seeds the swarm from a public git URL instead.
- `--watch` follows it live and exits **0** when it succeeded, **2** when it failed, **3** when canceled, and **1** on a CLI error.
- Without `--watch`, `run` prints the swarm id (`sw_…`) and returns at once. Follow it later with `acyclic swarm watch <id>`.
- Write the task like a ticket: the goal, the constraints ("do not edit the tests"), and how to verify ("run pytest").

## 4. Questions from the swarm (they never block)

A swarm may ask you a question (`acyclic.ask_user`). **It does not wait for the answer.** It keeps working on its recommended option. If nobody answers before the question expires, that option stands. So answer promptly, or not at all.
- `acyclic swarm watch <id>` prints the question, its numbered options and the deadline.
- `acyclic swarm answer <id> --option 2` chooses an option, numbered from 1.
- `acyclic swarm answer <id> --text "…"` answers in words, or adds a note to `--option`.
- `acyclic swarm answer <id> --default` keeps the swarm's assumption.

If you want a decision before any change, say so in the task. The swarm will still not pause, but it will ask early.

## 5. Take the result

A swarm's result exists only after it finishes, so wait with `watch` first.

    acyclic swarm pull <id> --apply          # apply the patch to this checkout; the change is STAGED
    git diff --cached                        # review it (a plain `git diff` shows nothing)
    acyclic swarm pull <id> --patch out.patch   # or keep the raw patch

`pull <id>` with no flags lists the files the swarm added. It writes nothing unless you name files or pass `--all`.

## 6. Inspect and debug

- `acyclic swarm ls`: recent swarms, newest first.
- `acyclic swarm show <id>`: the agent tree, result, spend by role and timings.
- `acyclic swarm trace <id>`: critical path, slowest spans and a text waterfall.
- `--json` on any command prints machine-readable JSON (NDJSON for streams).
- Every error from the service ends with `[X-Trace-Id: …]`. Quote it when reporting a problem.
- `acyclic swarm cancel <id>` stops a swarm and its sandboxes.

## MCP (no install)

`acyclic swarm mcp-config` prints a client config for `https://acyclic.dev/mcp`, with a 90-day token. The tools are:
- `spawn_swarm`, `list_swarms`, `swarm_status`, `cancel_swarm`
- `wait_swarm`: blocks up to 55 seconds and returns when the swarm ends; call it again while it is still running, instead of polling `swarm_status`
- `answer_swarm_question` (options numbered from 1, as `swarm_status` lists them)
- `swarm_files`, `read_swarm_file`, `swarm_diff`
- `swarm_diff` with `link_only: true` returns a 10-minute link and the command to apply it: `curl -fsSL '<link>' | git apply --3way`. The change is staged, so review it with `git diff --cached`
- `open_pull_request`, `list_swarm_tools`

## Cost

Swarms are billed at cost, sandbox time plus model usage, against prepaid credit and then a card. A small single-agent fix costs a few cents. Each swarm has a budget cap. The dashboard's Billing page shows the charge for every swarm.

## Links

- CLI install and quick start: https://acyclic.dev/cli
- All guides: https://acyclic.dev/guides
- Setup guide, step by step with a 37-second video: https://acyclic.dev/guides/setup
- MCP guide: https://acyclic.dev/guides/mcp
- Swarms as a tool in your own agent harness: https://acyclic.dev/guides/agent-tool
- Models, including GPT-6.1 Sol Ultrafast (`--model gpt-6.1-sol-ultrafast`, or `model` on spawn_swarm): https://acyclic.dev/guides/models
- GCP and SkyPilot from a swarm, as markdown: https://acyclic.dev/guides/gcp-skypilot.md
- Use your own OpenAI key for swarm model calls, as markdown: https://acyclic.dev/guides/openai-key.md
- Dashboard: https://acyclic.dev/dashboard