# Swarm tools (for AIs)

Swarm Control is an MCP server on the Swarm machine at `http://127.0.0.1:7783/mcp`, authorized with `Authorization: Bearer <contents of ~/.config/swarm/ai-key>`. Every tool is one stateless JSON-RPC `tools/call`; `tools/list` returns the default set with full argument schemas. Advanced tools stay callable by name and are listed with `/mcp?tools=all`. Trust `tools/list` on the person's machine over this page when they differ.

Key levels: **read** sees status, jobs and results; **write** (the installer's AI key) also gives jobs, deploys workers, schedules, makes media and delivers; **full** (`install.sh connect-ai --access full`) also changes limits and administration. Sign-in, keys and model administration are never offered over the relay.

## Models and providers

| Tool | What it does |
| --- | --- |
| `swarm_list_providers` | Which model providers are ready. |
| `swarm_connect_claude_code` | The person's Claude plan through Claude Code on the machine: `action: status` says what is missing and the command the person runs; `action: activate` once it reports signed in. Swarm never handles Claude credentials. |
| `swarm_connect_chatgpt` | Sign in the person's ChatGPT plan: `action: start` returns a URL and code to give the person at once; `action: status` with `login_id` until `success`. |
| `swarm_list_models` | Models per provider and the model each worker role uses (and which offer `fast`). |
| `swarm_set_agent_model` | Change a role's model (`system-coder`, `system-designer`, `system-finder` or all). Only when the person asks. |

## Projects and folders

| Tool | What it does |
| --- | --- |
| `swarm_create_project` | A project: a name and the person's folders (absolute paths). Nothing in them changes; Swarm writes `project.md` from them. |
| `swarm_list_workspaces`, `swarm_add_workspace` | Registered folders. A folder under a home directory may need `install.sh workspace add PATH --for-user USER` as root first (`workspace_not_visible`). |
| `swarm_set_environment`, `swarm_get_environment` | A folder's environment: a base image plus setup commands and `max_leases` (how many agents use it at once). Every agent's bash in that folder then runs inside it by itself, with the folder's granted secrets as stand-ins. Needs Docker: if Swarm says environments are off, the person runs `sudo bash /var/lib/swarm-headless/install.sh environments on`. Without one, agents run commands on the machine as Swarm's user. |

## Delegate to Swarm

| Tool | What it does |
| --- | --- |
| `swarm_run_task` | `{project_id, brief}`: hand a goal to Swarm; it plans it and splits it across its coder, designer and finder. Returns task and session receipts. |
| `swarm_wait_task`, `swarm_task_result` | Wait for the task, then read its result, branch and evidence. |
| `swarm_send_message`, `swarm_stop_run` | Continue in the same session; stop its active run. |
| `swarm_integrate_task` | Merge a reviewed task's branch, with integration evidence. Only when the person wants it. |

## Workers and jobs (straight to one worker)

| Tool | What it does |
| --- | --- |
| `swarm_list_workers` | The built-in coder, designer and finder, plus deployed workers. |
| `swarm_deploy_worker` | A worker of your own: a name, a role (coder, designer, finder or reviewer) and standing instructions. |
| `swarm_manage_worker` | Pause, resume or change a deployed worker. |
| `swarm_give_job` | `{worker, project, brief}` (a folder too when the project has several). Returns a `job_id`. The job runs on its own branch. |
| `swarm_get_job` | Wait (`wait_seconds` up to 110) and read the job: status, open questions, branch, commits, files, report, cost, merge state, and with `include_diff` the diff. Media jobs list their files; `include_media` returns images. |
| `swarm_message_job` | A follow-up in the same job and branch: more to do, a correction, a redo. |
| `swarm_answer_job` | Reply when a worker asks a question (`needs_input`). Never a tool-call approval. |
| `swarm_deliver_job` | Deliver a finished job: a local git merge into the folder, or a pull request when publishing is set up for it. Swarm never pushes otherwise. |
| `swarm_stop_job` | Cancel a job. |
| `swarm_list_runs` | Runs across workers, including scheduled ones. |

## Workflows

| Tool | What it does |
| --- | --- |
| `swarm_schedule_job` | A worker that runs one job on a schedule in one folder: cron with a timezone (e.g. `0 8 * * *`, `Europe/Berlin`) or every N seconds (at least 60). Each run is a job you read with `swarm_get_job`. |
| `swarm_set_automation`, `swarm_list_automations`, `swarm_delete_automation` | What Swarm does when a job ends in a folder: ordered steps, each the machine owner's script (`run`), a job for a worker such as the reviewer (`agent`), or sending the job back with feedback (`reopen`, bounded by `max_rounds`). Scope: the folder, one worker, one job or one schedule; when succeeded, failed or always. Offer it; do not set it up unasked. |

Programs can also trigger a worker on demand (a webhook, a CI event, an alert payload) through the SDK with a token scoped to `automations:trigger`: see https://swarmagent.dev/ai/sdk.md.

## Media

| Tool | What it does |
| --- | --- |
| `swarm_media_models` | Each ready image, video and sound model with its aspect ratios, resolutions, lengths, counts, image input, operations and pricing, plus the default per kind. |
| `swarm_request_media` | `kind` and `brief`, optionally `model`, `aspect_ratio`, `resolution`, `duration_seconds`, `count`, `operation` (create, extend, edit) and `inputs` (an earlier media job's file or a file in a registered folder). Checked against the model before anything is spent. |
| `swarm_save_media` | Write a media job's files into a folder of a project (never overwriting). |
| `swarm_set_media_models` | The default model per media kind. Only when the person asks. |

## Monitoring, limits and secrets

| Tool | What it does |
| --- | --- |
| `swarm_status` | One call: `ok`, `attention` or `degraded` with reasons (the sandbox and secret gateway when they are on, jobs waiting on the person, failures today, spend against the daily limit). |
| `swarm_activity` | The signal feed after a cursor: finished and failed runs, blocked workers, refused connections, with job ids. See https://swarmagent.dev/ai/alerts.md. |
| `swarm_get_usage` | Spend and usage. |
| `swarm_get_limits`, `swarm_set_limits` | Spending limits (setting them needs a full key). |
| `swarm_list_secrets` | Which secrets exist, which websites they may go to and which folders may use them. Never values. |

## Keys

Every key works while it is used and stops after 90 days without use (or at a fixed end date, if one was given). Nothing needs renewing.

| Tool | What it does |
| --- | --- |
| `swarm_list_keys` | Every key: kind (AI, app, bot), options, state, when and where it was last used, every place it was used from, and when it stops on its own. `this_key` marks yours. Never key material. |
| `swarm_create_key` | A full key makes an app key (`access`: sessions or monitor) or a bot key (`agent`, `operator`, limits), shown once. `days` only for a fixed end date. AI keys come from the installer (`connect-ai`). |
| `swarm_revoke_key` | Stop a key now, and every key made with it. |

`swarm_status` lists keys used from a new place today and keys that stop within a week; the signals are `key.new_address` and `key.expiring`.

## Many machines (the fleet MCP)

`swarm-fleet` adds a `machine` argument to every tool above and three of its own: `swarm_fleet_status` (every machine: reachable, access level, running sessions, today's usage and limits, its `swarm_status`), `swarm_fleet_models` (the fleet model table and per-machine drift) and `swarm_fleet_set_models`. See https://swarmagent.dev/ai/fleet.md.