SETUP / FIRST TASK / HANDOFF

Install SwarmForge
and run coding agents.

SwarmForge is a self-hosted orchestration platform for autonomous AI coding agents running in isolated VMs. You provide the VM snapshot, model endpoint, and source repository; SwarmForge coordinates workers and preserves their deliverables.

1. Have your providers ready

• A Linux x64 machine to run the control plane, with Bash, curl, GNU tar and coreutils. No Bun or source checkout is required for the compiled release.
• A Freestyle API token and prepared snapshot. The snapshot needs OpenCode, Python 3, Git, systemd, and the configured writable workspace.
• An OpenAI-compatible model endpoint that supports tool calls, an API key, and its exact model name.
• A Git clone URL or an externally managed source tree.

Use a normal user account. The installer does not need sudo and refuses root execution.

2. Install and onboard

curl -fsSL https://getswarmforge.tech/install | bash

The installer resolves a published stable GitHub release, verifies the archive and executable SHA-256, then atomically installs ~/.local/bin/swarmforge. In an interactive terminal it configures the CLI and runs local readiness checks. Existing configuration survives reruns.

The first published release must be available for installation to succeed. If no stable release exists, the installer reports that and changes no executable. Check GitHub Releases for availability.

You can read the installer before executing it:

curl -fsSL https://getswarmforge.tech/install -o install.sh
less install.sh
bash install.sh

Options for existing deployments and automation

# Install the executable without configuration prompts
curl -fsSL https://getswarmforge.tech/install | bash -s -- --install-only

# Install a specific published release
curl -fsSL https://getswarmforge.tech/install | bash -s -- --version 0.1.2 --install-only

# Leave shell profiles unchanged
curl -fsSL https://getswarmforge.tech/install | bash -s -- --no-modify-path

SWARMFORGE_INSTALL_DIR accepts an absolute installation directory. The installer can add an idempotent PATH line for Bash, Zsh, or Fish, and prints instructions for other shells. Open a new terminal afterward. In an editor, reload the workspace and open a new terminal.

SHA-256 checks detect corruption; the installer currently does not verify a publisher signature. All release assets are fetched over HTTPS from the application's GitHub repository.

3. Configure your deployment

Interactive installation invokes swarmforge init when you have no existing configuration. To configure later:

mkdir -p ~/swarmforge-deployment
cd ~/swarmforge-deployment
swarmforge init
swarmforge doctor

Initialization asks for:

Credential entry is hidden. The CLI creates a private .env in the current directory and, when no global config exists, registers it for commands run from other directories. It preserves an existing global config. Never commit this file or source it as shell code.

# Use an explicit environment file when needed
swarmforge doctor --env-file .env
swarmforge serve --env-file .env

Ordinary doctor checks are local. The optional swarmforge doctor --live contacts providers and makes a small model inference request. It does not provision VMs. To additionally inspect guest tools, supply --vm with an existing running VM based on the configured snapshot.

4. Start and connect

swarmforge serve

Keep that terminal open. In another terminal:

swarmforge status

Configure your MCP client with a Streamable HTTP server URL. With default settings:

http://127.0.0.1:8787/mcp

Client configuration syntax varies by application. If the server requires authentication, supply its bearer token in the client's supported header configuration. SWARMFORGE_API_TOKEN is required for a non-loopback accepted host. The installer does not silently edit MCP client files or expose your control plane publicly.

See the application README for configuration relationships and startup troubleshooting.

5. Give a worker a concrete task

Ask your MCP manager to use spawn_worker. Start with a small task and an explicit deliverable:

{
  "team_id": "default",
  "task_id": "first-review",
  "request_id": "first-review-v1",
  "template": "review",
  "prompt": "Review the repository setup instructions. Report concrete issues with file locations. Do not change source.",
  "timeout_seconds": 900
}

This is an MCP tool invocation, not a shell command. It creates a VM and may incur provider charges. The review template requests .swarmforge/artifacts/review.md. Use a stable request ID for safe retries of the same request.

Inspect the worker with get_worker, collect the persisted result with get_worker_result, and use the dashboard to see response activity, reported test outcomes, preservation state and recovery guidance.

6. Collect deliverables before cleanup

swarmforge artifacts list --worker <worker-id>
swarmforge artifacts preview <artifact-id>
swarmforge artifacts download <artifact-id> --output ./review.md

Previews return bounded credential-screened text. Complete downloads are authenticated, size/checksum verified, and refuse existing destination files. Preserved results and artifacts survive VM destruction.

In the dashboard, Enter opens details; a browses artifacts, p previews a selected artifact, and Enter in the artifact browser saves it. Cleanup checks settled state, pending work, artifact preservation, and Git safety before normal destruction.

7. Operate your team

swarmforge templates list
swarmforge usage --json
swarmforge retention preview
swarmforge notifications watch

Cost estimates require explicitly configured rates and disclose unpriced usage. Budget thresholds emit alerts; they are not enforced spending limits. Automatic VM retention cleanup is disabled by default. Press Tab in the overview to switch between the chibi status view and the technical dashboard. The dashboard's n key opens durable notifications, and PgUp/PgDn scroll long details and previews.

See operator workflows for policy settings, usage coverage, search filters, and notification cursors.

Understand the technical concepts

These guides define the current implementation and its boundaries.

• Workers and isolated environments — Understand how SwarmForge runs OpenCode workers in isolated Freestyle VMs, queues capacity, reuses sessions, and preserves outputs.
• Tasks, teams and follow-up messages — Learn how SwarmForge groups workers by task and team, deduplicates creation requests, and queues follow-up turns.
• Managers and MCP coordination — Understand the MCP manager role in SwarmForge and how it delegates, observes, reviews and integrates parallel coding work.
• VM providers and model endpoints — SwarmForge currently uses Freestyle VMs and OpenCode with an OpenAI-compatible tool-calling model endpoint. Learn the deployment requirements.
• Repositories and Git handoffs — How SwarmForge prepares a configured Git workspace, hands off verified branches, and protects local-only source work during cleanup.
• Artifacts and durable deliverables — SwarmForge preserves worker files in private coordinator storage, with bounded text previews and checksum-verified downloads.
• Metrics, token usage and cost estimates — Track SwarmForge workers, measured token usage, preservation and retained VM estimates through the CLI and Prometheus metrics.

Continue with the system architecture, coding workflows, frequently asked questions or benchmark methodology.

Troubleshooting and upgrades

• Command not found: open a new terminal, or add the selected installation directory to your shell's PATH.
• No published stable release: check the Releases page; a draft release cannot be downloaded by the public installer.
• Configuration already exists: keep it and run doctor with the applicable --env-file. Init deliberately refuses to overwrite a local .env.
• Provider/model failure: inspect local doctor output, then explicitly invoke live doctor if appropriate. A configured endpoint can be reachable yet incompatible with the worker protocol.
• Upgrade: rerun the installer with --install-only. An already-running server retains its old executable; restart it deliberately and reconnect MCP clients to load the new version.
• Uninstall: remove the installed executable and its PATH line. Configuration, database, and artifact storage remain until you remove them explicitly. Stop a running server before removing its deployment data.