Swarm

Swarm runs AI agents on your own machine, and your AI tells them what to do.

Install it on a Linux machine (your own PC or a server). Your AI (Claude Code,
Codex, ChatGPT) connects to it and gets work done in your folders two ways:

Delegate a goal to Swarm. It plans the work and splits it across its
coder, finder and designer.
Give a job straight to a worker: the coder (code), designer (UI
and HTML designs), finder (research and audits), reviewer (reviews
another job), media (images, video, sound), or your own workers.

Every job works on its own branch and comes back with a report and its cost;
your AI reviews it and merges it. When you want more:

Workers: your own named workers with standing instructions.
Schedules: a worker runs a job every N minutes or on cron.
Automations: steps that run when a job ends: your script, another agent
(a reviewer, say), or sending the job back with feedback.
Environments: a folder's own container (a base image plus setup) that its
agents' commands run in, with that folder's secrets. Agents see stand-ins;
the real value goes out only to the websites you allowed.
Monitoring and alerts: your AI asks whether Swarm is all right and what
happened (jobs finished or failed, cost, workers blocked); signals go to a
webhook or Telegram.

By default agents run on the machine as Swarm's own user, without permission
prompts and without a sandbox; install.sh sandbox on runs every command in
one container per project. There is no dashboard to learn: you talk to your
AI, it talks to Swarm through its MCP tools. The only page is the setup page
where you type your keys (or a script does it). A desktop app comes later, on
top of this.

This repository is under active development; this README describes what the
current code does.

Install

Ubuntu 24.04, x86_64. From your own account:

curl -fsSL https://swarmagent.dev/install | sudo bash

It downloads the newest release of Swarm, checks it against its published
checksum and runs Swarm and its setup page as services under Swarm's own
swarm user, listening on 127.0.0.1 only. Nothing is compiled and no Docker is
installed. At the end it creates Swarm's owner for you, puts an AI key for your
AI in ~/.config/swarm/ai-key (only you can read it) and prints how to
connect. Add --environments on (or run install.sh environments on later)
for environments, which need Docker; add --tailnet only to reach this
machine from your other devices. Details: containers/headless/app/README.md.

Your model provider key goes on the setup page (http://127.0.0.1:8443) or in
by script, never through chat:

sudo bash /var/lib/swarm-headless/install.sh key PROVIDER < key-file

Connect your AI

Claude Code: install the swarm plugin. It finds ~/.config/swarm/ai-key
by itself (it needs Node 22+) and brings Swarm's skills:

claude plugin marketplace add swarm-agent/swarm
claude plugin install swarm@swarm

or add only the tools:

claude mcp add --scope user --transport http swarm http://127.0.0.1:7783/mcp --header "Authorization: Bearer $(cat ~/.config/swarm/ai-key)"

Codex: the installer prints the line (it reads the key from an
environment variable).

Then tell your AI: "set up Swarm". It checks for a model provider (your
ChatGPT or Claude plan, or an API key), asks which folders your work is in,
creates a project with them, and gives the first piece of work.

Building your own frontend (a console, a dashboard, a setup flow for your
AI)? docs/frontends.md is the path: find Swarm without a
key (GET http://127.0.0.1:7783/v3/hello), install it, give your app its own
key (install.sh connect-app NAME), set up a provider and a project, then
follow the activity feed.

What your AI does with it

Tool	What it does
`swarm_list_providers`, `swarm_list_models`	which providers are ready; the model each worker role uses
`swarm_connect_chatgpt`, `swarm_connect_claude_code`	sign in with your ChatGPT plan, or use your Claude plan through Claude Code
`swarm_set_agent_model`	change a role's model (only when you ask)
`swarm_create_project`	a project: a name and your folders (nothing in them is changed)
`swarm_run_task`, `swarm_wait_task`, `swarm_task_result`	delegate a goal to Swarm, which splits it across its coder, finder and designer
`swarm_give_job`	give one worker (coder, designer, finder, reviewer or your own) a job in a project's folder
`swarm_get_job`	wait for it; the result: branch, commits, files, report, cost, diff, transcript
`swarm_message_job`	a follow-up in the same job: more to do, a correction, a redo
`swarm_answer_job`	reply when a worker asks something
`swarm_deliver_job`	deliver the result: a local git merge into the folder, or a pull request when you set up publishing for it (`install.sh workspace publish`); Swarm never pushes otherwise
`swarm_request_media`	an image, video or sound
`swarm_deploy_worker`	your own worker: a name, a role, standing instructions
`swarm_schedule_job`	a worker that runs a job on a schedule
`swarm_set_workflow`, `swarm_list_workflows`	a workflow: steps that run when a task of Swarm's own agents (coder, finder, designer, swarm) or a worker job ends: another agent such as a reviewer, sending the work back to the agent that did it, or your script to push, deploy or alert
`swarm_set_environment`, `swarm_get_environment`	a folder's environment: a base image plus setup commands, built by Swarm, with `max_leases`
`swarm_status`, `swarm_activity`	is Swarm all right; what happened since last time
`swarm_list_secrets`	which secrets exist and which folders may use them (never values)

Advanced tools (sessions, plans, project orchestrators, tasks by role) stay
available: /mcp?tools=all. The full catalog and the trust boundary:
docs/checkpoints/swarm-control.md.

Architecture

Swarm is split into a launcher, a terminal UI, a daemon, and a web frontend:

Area	Path	Purpose
Launcher CLI	`cmd/swarm/`, `internal/launcher/`	Manages the installed daemon service, records port metadata, launches TUI or desktop controllers, runs update helpers.
Installer	`cmd/swarmsetup/`	Installs launchers and release artifacts into system locations.
Terminal UI	`cmd/swarmtui/`, `internal/app/`, `internal/ui/`	tcell app, slash commands, modals, settings, model/auth/workspace/session UI.
Daemon	`swarmd/`	HTTP/WebSocket API, provider runtime, sessions, workspaces, permissions, Pebble-backed persistence.
Desktop UI	`web/`	Vite/React browser frontend served by the local runtime.
Tests and harnesses	`tests/`, `swarmd/tests/`, `scripts/`	Unit tests, integration tests, e2e harnesses, release and policy checks.

swarmd exposes health endpoints plus authenticated local API routes for auth credentials, provider status, model preferences/catalogs, workspaces, sessions, UI settings, permissions, and streaming session events.

Privacy and anonymous mint reporting

When a new local swarm identity is generated for the first time, swarmd makes one best-effort HTTPS request to https://swarmagent.dev/api/mint. The request contains only payload version 1 and a one-way anonymous identifier derived locally from the random swarm ID. It does not send the raw swarm ID or user, machine, network, key, account, workspace, provider, or session data. Delivery state is stored locally so transient failures can retry on a later start without delaying or preventing daemon startup; existing and explicitly restored identities are not reported as new mints.

Data and configuration locations

Swarm uses system locations for Swarm-owned daemon state. By default it does not write daemon databases, secrets, runtime files, logs, caches, generated artifacts, downloads, reports, or worktrees under a user home directory, XDG user directory, repository checkout, or current working directory.

Linux defaults:

/usr/local/bin for launchers.
/usr/local/share/swarm/{bin,libexec,lib,share} for runtime files.
/etc/swarmd for daemon configuration.
/var/lib/swarmd for daemon data, databases, secrets, generated artifacts, reports, and worktrees.
/var/cache/swarmd for daemon caches.
/run/swarmd for volatile runtime files, sockets, locks, and PID files.
/var/log/swarmd for logs and diagnostic artifacts.

macOS support is not yet the primary installer target, but the storage contract is prepared for system-level locations: /Library/Application Support/Swarm/swarmd for data, /Library/Application Support/Swarm/swarmd/config for configuration, /Library/Caches/Swarm/swarmd, /var/run/swarmd, and /Library/Logs/Swarm/swarmd. Future macOS installer work should provision those system roots rather than user ~/Library locations.

Swarm intentionally does not silently migrate or reuse legacy home/XDG/workspace daemon data. If legacy startup config or secrets are detected, startup stops with a diagnostic telling you which legacy path exists and which system path is expected. Move data only after an explicit backup and operator-controlled migration.

UI settings are persisted through the daemon-backed /v1/ui/settings API. Current settings include chat header visibility, thinking tags, tool stream display, mouse capture, keybinds, theme selection, custom themes, and swarm display metadata.

Development

Run the repository pre-commit gate before committing changes:

./scripts/check-precommit.sh

That gate includes repository policy checks, secret checks, hardcoded-path checks, and vulnerability scanning. Additional development scripts live under scripts/.

Live candidate testing runs in the release pipeline, not from this checkout. The host Swarm service and host ports 5555/7781 are not a live candidate-test target.

Common source-checkout commands:

./setup
./rebuild dev
swarm dev
swarm dev info

Suggested GitHub repository metadata

These fields must be set in the GitHub repository UI by a maintainer:

About description

Swarm runs AI agents on your own machine for your AI (Claude Code, Codex, ChatGPT): workers, jobs, schedules, automations, environments and monitoring over MCP.

Topics

ai-coding-agent, developer-tools, terminal-ui, tui, desktop-app, go, golang, local-first, multi-agent, coding-assistant, llm, ai-tools, workspace-management, permissions, websocket, react, vite, pebble, cli, open-source

License

Apache License 2.0. See LICENSE.

Sandbox build caches

Installed sandboxes share a project-local Go build/module cache and pnpm store
across jobs and reviewers, including custom environments. -trimpath enables
reuse across checkout paths. Configure the per-project soft limit with
project_cache_bytes in the durable box limits via swarm_set_limits (default
10 GiB; read live at trimming time). The image's warm pnpm store is seeded too.
See sandbox resources for seeding, concurrency,
size reporting, and trimming limitations.