swarmclawai/swarmclaw

SwarmClaw

The self-hosted AI agent runtime and multi-agent framework for autonomous agents. Open-source agent swarms with durable agent memory, MCP tools, skills, delegation, schedules, and 23+ LLM providers — a practical Claude Code and LangChain alternative.

SwarmClaw is an open-source, self-hosted AI agent runtime and multi-agent framework. Run autonomous AI agents, agent swarms, and orchestrators with heartbeats, schedules, delegation, agent memory, runtime skills, and reviewed conversation-to-skill learning — across OpenClaw gateways, Claude, GPT, Gemini, OpenRouter, Ollama, and 23+ other providers. Use it as your AI agent dashboard, agent orchestration platform, and home base for self-hosted multi-agent AI workflows.

GitHub: https://github.com/swarmclawai/swarmclaw Docs: https://swarmclaw.ai/docs Website: https://swarmclaw.ai Discord: https://discord.gg/sbEavS8cPV Extension tutorial: https://swarmclaw.ai/docs/extension-tutorial

Screenshots

Org chart for visualizing agent teams, delegation, and live activity.	Agent chat with durable history, tools, and operator controls.

Requirements

• Node.js 22.6+ (nvm use will pick up the repo's .nvmrc, which matches CI)
• npm 10+ or another supported package manager
• Docker Desktop is recommended for sandbox browser execution
• Optional provider CLIs if you want delegated CLI backends such as Claude Code, Codex, OpenCode, Gemini, Copilot, Factory Droid, Cursor Agent, Qwen Code, or Goose

Quick Start

Desktop app (recommended for non-technical users)

Download the one-click installer from swarmclaw.ai/downloads. Available for macOS (Apple Silicon & Intel), Windows, and Linux (AppImage + .deb).

The release workflow supports Developer ID signing and notarization when Apple credentials are configured. If a macOS build is still ad-hoc signed, first launch may need one manual approval:

• macOS: signed/notarized releases publish both .dmg and .zip; unsigned fallback releases publish .zip only to avoid the damaged unsigned DMG path. Right-click the app in Finder → Open → Open to bypass Gatekeeper. If macOS instead reports "SwarmClaw is damaged and can't be opened" (common when a downloaded app was quarantined by Safari), strip the quarantine attribute and relaunch:

  xattr -dr com.apple.quarantine /Applications/SwarmClaw.app
  

• Windows: if SmartScreen appears, click More info → Run anyway.
• Linux (AppImage): chmod +x the downloaded file, then run it.

Data lives in your OS app-data directory (~/Library/Application Support/SwarmClaw, %APPDATA%\SwarmClaw, or ~/.config/SwarmClaw), separate from any CLI or Docker install.

Global install

npm i -g @swarmclawai/swarmclaw
swarmclaw

yarn global add @swarmclawai/swarmclaw
swarmclaw

pnpm add -g @swarmclawai/swarmclaw
swarmclaw

bun add -g @swarmclawai/swarmclaw
swarmclaw

Running swarmclaw starts the server on http://localhost:3456.

From the repo

git clone https://github.com/swarmclawai/swarmclaw.git
cd swarmclaw
nvm use
npm run quickstart

npm run quickstart installs dependencies, prepares local config and runtime state, and starts SwarmClaw.

Docker

git clone https://github.com/swarmclawai/swarmclaw.git
cd swarmclaw
mkdir -p data
touch .env.local
docker compose up -d --build

Then open http://localhost:3456.

ClawHub Skill

Install the SwarmClaw skill for your OpenClaw agents:

openclaw skills install swarmclaw

Browse on ClawHub

v1.9.39 Highlights

Scheduled-run reliability release: stale workspace rebinding, fail-fast credential checks, and durable delivery evidence for schedule-driven sends.

• Legacy workspace cwd migration. Scheduled reruns and reused schedule sessions pinned to a pre-migration workspace root (e.g. ~/.swarmclaw/workspace) are now rebound to the current WORKSPACE_DIR automatically; intentional custom working directories are never touched.
• Orphan recovery dedup. Startup queue recovery now recovers each orphaned task once instead of re-logging it every tick, and dead-letters tasks that repeatedly return to the queue without starting.
• Schedule delivery status. Every scheduled run now writes lastDeliveryStatus/lastDeliveryError back to its schedule, so failures are visible without digging through task records.
• Credential preflight for schedules. Scheduled runs on API-key providers fail fast with an actionable error when no credential resolves, instead of dying on a 401 deep in execution.
• Empty-run classification. Runs that produce no text, no tool calls, and no error now fail with a clear provider-configuration message instead of a generic validation failure.
• Durable connector delivery evidence. Task follow-up sends route through the connector outbox with task/schedule linkage, retries with backoff, and per-run dedupe, so triage can prove whether a scheduled send succeeded, failed, or was never attempted.
• Regression coverage. Added tests for workspace path normalization, orphan recovery, schedule outcome writes, credential preflight, empty-run classification, and outbox-backed follow-ups.

v1.9.38 Highlights

PR integration release for provider catalog coverage, OpenRouter context meters, and safer unsigned macOS desktop artifacts.

• TokenMix provider. Added TokenMix as a built-in OpenAI-compatible provider with setup metadata, starter-agent defaults, and provider health checks.
• OpenRouter context meters. Chat context status now uses cached OpenRouter model metadata when available so routed model context windows display accurately.
• macOS unsigned artifact fallback. Desktop releases publish zip-only macOS artifacts when signing/notarization inputs are missing, avoiding the unsigned DMG damaged-app path.
• Regression coverage. Added targeted tests for TokenMix setup, OpenRouter context metadata caching, and macOS target selection.

v1.9.37 Highlights

Theme and memory-pressure release for lighter UI preferences and leaner chat history storage.

• Light, dark, and system theme modes. Settings → Appearance now persists a Light/Dark/System selector while keeping the existing hue presets and custom color picker.
• Lean session history storage. Legacy transcript blobs migrate into the session_messages table and are compacted from session records after persistence is verified, reducing page-load memory pressure on lower-RAM devices.
• Repo-backed message readers. Global search, live usage summaries, and OpenClaw history merge now read table-backed messages after transcript compaction.
• Regression coverage. Added tests for theme-mode normalization, legacy transcript compaction, and repo-backed message search.

v1.9.36 Highlights

Protocol builder visibility release for built-in Structured Sessions.

• Built-in flow inspector. Built-in protocol templates now open in a full-size visual builder canvas with a read-only template step panel.
• Canvas viewport repair. Builder routes now claim the full dashboard workspace and refit React Flow after async template loads.
• Regression coverage. Browser smoke now verifies that the built-in facilitated discussion graph renders with visible flow nodes.

v1.9.35 Highlights

Installed package build fix for fresh npm-global installs and upgrades.

• Fallback build dependency fix. The npm package now declares mime-types and @types/mime-types directly so swarmclaw server --build can type-check the OpenClaw media proxy on clean installs.
• Installed-build regression guard. CLI/package tests now verify that unbundled type declarations needed by local fallback builds ship as runtime package dependencies.
• macOS desktop status. The damaged-app issue remains open until Developer ID signing and Apple notarization are configured and verified on downloaded macOS artifacts.

v1.9.34 Highlights

Credential recovery and external extension access release for npm-global upgrades and scoped agent tool configuration.

• Credential secret recovery. Startup now checks prior npm-global build env files before accepting a fresh per-version CREDENTIAL_SECRET, and validates candidate secrets against existing encrypted credentials before persisting DATA_DIR/credential-secret.
• Clear connector failures. Connector startup now logs and surfaces credential decrypt failures directly instead of falling through to a misleading "No bot token configured" error.
• External extension tools. Scoped agents now keep explicitly attached external .js and .mjs extensions, and the agent/chat tool controls persist enabled external tools through the extensions field.
• Regression coverage. Added tests for previous-build credential recovery, non-decrypting secret replacement, scoped external extension access, and extension access persistence.

v1.9.33 Highlights

Issue and PR validation release for credential durability, delegated task dispatch, connector output hygiene, and OpenClaw gateway protocol compatibility.

• Credential durability. Execute-tool credential injection now reads the persisted encryptedKey field, and CREDENTIAL_SECRET now resolves in a stable order: explicit environment value, DATA_DIR/credential-secret, legacy env files, then generated fallback.
• Delegated task dispatch. Agent-created tasks delegated to another agent auto-queue when no explicit status is supplied, and failed dead-lettered tasks can be requeued through POST /api/tasks/:id/retry.
• Connector output hygiene. Connector replies now reuse the internal metadata scrubber before delivery and persistence, while successful non-connector delivery tool output is no longer overwritten as an unconfirmed send.
• Agent and gateway compatibility. Agent updates preserve workspace filesystem settings, and OpenClaw gateway routes now use protocol version 4.
• Regression coverage. Added tests for credential env injection, secret precedence, delegated queueing, failed-task retry, connector sanitization, agent workspace settings, and OpenClaw gateway protocol exports.

v1.9.32 Highlights

PR integration release for background model routing, reflection memory controls, and current ClawHub install guidance.

• Background model routing. Per-agent dreamConfig overrides can route dream cycles and daily digests before global dream settings, while compactionProvider settings can route live auto-compaction summaries through a cheaper or faster model.
• Reflection memory controls. reflectionMinQuality gates automatic reflection memory writes without dropping the reflection record, and optional embedding dedup skips near-duplicate reflection notes when embeddings are configured.
• ClawHub install guidance. OpenClaw skill docs now use openclaw skills install swarmclaw and current owner-scoped ClawHub links.
• Regression coverage. Added tests for dream override precedence, compaction preference resolution, reflection quality gating, and embedding-based reflection dedup.

v1.9.31 Highlights

Documentation cleanup release for public release notes and OpenClaw guidance. No runtime behavior changed.

• Public docs cleanup. Removed an unwanted third-party example from the README and site release notes.
• OpenClaw guidance preserved. The README keeps the SwarmClaw-native OpenClaw gateway, skill, and agent-file guidance without naming unrelated workflows.

v1.9.30 Highlights

PR integration release for dream-model routing, email bridge TLS opt-outs, and installed CLI runtime resolution.

• Dream model routing. Memory dream cycles and daily digests can use optional dreamProvider settings so background consolidation can run on a smaller local model.
• Email bridge TLS opt-outs. tlsRejectUnauthorized=false now disables hostname checks too, matching the explicit self-signed-server opt-out.
• Installed CLI stability. Legacy API-backed CLI commands import the package-local tsx runtime instead of resolving tsx from the caller's project.

v1.9.29 Highlights

Issue-fix release for Edit Agent tooltips, installed package builds, and structured dream output on local Ollama models.

• Edit Agent tooltips. Help tips in the Edit Agent sheet now render above modal layers instead of being hidden behind the dialog.
• Installed package builds. The npm package now ships the Dagre type declarations needed by swarmclaw server --build.
• Local Ollama dream output. Structured dream/reflection calls request Ollama JSON mode and validate balanced JSON before writing memories.
• Regression coverage. CLI/package, model-build, and dream-parser tests cover the reported failure modes.

Hosted Deploys

SwarmClaw now ships provider-ready deploy files at the repo root:

• render.yaml for Render Blueprint deploys from the public GHCR image
• fly.toml for Fly.io image-backed deploys
• railway.json for Railway-aligned health and restart defaults

The published image is:

ghcr.io/swarmclawai/swarmclaw:latest

Hosted deployments should:

• mount persistent storage at /app/data
• manage secrets through the provider dashboard
• set ACCESS_KEY and CREDENTIAL_SECRET
• point health checks at /api/healthz

Full hosted deployment guides live at https://swarmclaw.ai/docs/deployment

Core Capabilities

• Providers: 24+ built-in — Claude Code CLI, Codex CLI, OpenCode CLI, Gemini CLI, Copilot CLI, Cursor Agent CLI, Qwen Code CLI, Goose, Anthropic, OpenAI, OpenRouter, Google Gemini, DeepSeek, Groq, Together, Mistral, xAI, Fireworks, Nebius, DeepInfra, Ollama, LM Studio, OpenClaw, and Hermes Agent, plus compatible custom endpoints.
• OpenRouter: Use OpenRouter as a first-class built-in provider with its standard OpenAI-compatible endpoint and routed model IDs such as openai/gpt-4.1-mini.
• Hermes Agent: Connect Hermes through its OpenAI-compatible API server, locally or through a reachable remote /v1 endpoint.
• Delegation: built-in delegation to Claude Code, Codex CLI, OpenCode CLI, Gemini CLI, Cursor Agent CLI, Qwen Code CLI, and native SwarmClaw subagents.
• Autonomy: heartbeat loops, schedules, background jobs, task execution, supervisor recovery, and agent wakeups.
• Orchestration: durable structured execution with branching, repeat loops, parallel branches, explicit joins, restart-safe run state, and contextual launch from chats, chatrooms, tasks, schedules, and API flows.
• Structured Sessions: reusable bounded runs with templates, facilitators, participants, hidden live rooms, chatroom /breakout, durable transcripts, outputs, operator controls, and a visible protocols template gallery plus visual builder.
• Memory: hybrid recall, graph traversal, journaling, durable documents, project-scoped context, automatic reflection memory, communication preferences, profile and boundary memory, significant events, and open follow-up loops.
• Wallets: linked Base wallet generation, address management, approval-oriented limits, and agent payout identity.
• Connectors: Discord, Slack, Telegram, WhatsApp, Teams, Matrix, email, local file queues, OpenClaw, SwarmDock, SwarmFeed, and more.
• MCP Servers: connect any Model Context Protocol server (stdio, SSE, or streamable HTTP) and inject its tools into agents alongside built-ins. Configure, test, and assign per-agent from the MCP Servers panel.
• Extensions: external tool extensions, UI modules, hooks, install/update flows, and managed resource manifests for extension-owned agents, routines, local folders, gateways, and setup checks.

What SwarmClaw Focuses On

• Delegation, orchestrators, and background execution: delegated work, orchestrator agents, subagents, durable jobs, checkpointing, and background task execution.
• Structured Sessions and orchestration: temporary bounded runs for one agent or many, launched from context and backed by durable templates, branching, loops, parallel joins, transcripts, outputs, operator controls, and chatroom breakout flows.
• Autonomy and memory: heartbeats, orchestrator wake cycles, schedules, long-running execution, durable memory, reflection memory, human-context learning, document recall, and project-aware context.
• OpenClaw integration: named gateway profiles, external runtimes, deploy helpers, config sync, approval handling, and OpenClaw agent file editing.
• Runtime skills: pinned skills, OpenClaw-compatible SKILL.md import, on-demand skill execution, and configurable keyword or embedding-based recommendation.
• Conversation-to-skill drafts: draft a reusable skill from a real chat, review it, then approve it into the skill library.
• Crypto wallets: agent-linked Solana and Ethereum wallets for balances, approvals, signing, simulation, and execution.
• Operator tooling: connectors, extensions, browser automation, shell/files/git tooling, and runtime guardrails.

OpenClaw

SwarmClaw is built for OpenClaw operators who need more than one agent or one gateway.

• Bundle and use the official openclaw CLI directly from SwarmClaw.
• Connect each SwarmClaw agent to a different OpenClaw gateway profile.
• Discover, verify, and manage multiple gateways from one control plane.
• Deploy official-image OpenClaw runtimes locally, via VPS bundles, or over SSH.
• Edit OpenClaw agent files such as SOUL.md, IDENTITY.md, USER.md, TOOLS.md, and AGENTS.md.
• Import OpenClaw SKILL.md files and use them in SwarmClaw's runtime skill system.
• Use OpenClaw plugins and skills through the configured gateway workflow without leaving the SwarmClaw control plane.

Use Cases

SwarmClaw is a general-purpose agent runtime. Here are some of the ways people use it.

---

Personal Assistant

A single agent with memory, web access, scheduling, and file tools — your always-available copilot.

"Remember that I prefer window seats. Book research time every Monday at 9am. Summarize the articles I saved last week."

• Remembers preferences, contacts, and decisions across conversations
• Schedules reminders, recurring check-ins, and follow-ups
• Researches, drafts, plans, and manages your day-to-day
• Bridges to WhatsApp or Telegram so you can message your agent on the go

Starter kit: Personal Assistant → 1 agent, ready in under a minute.

---

Virtual Company

Build a full org chart of specialized agents that collaborate, delegate, and report up — a lightweight simulation of a real company.

| Role | Agent | Responsibilities | |------|-------|-----------------| | CEO | Strategist | Sets objectives, reviews progress, delegates to department heads | | CTO | Builder | Owns technical execution, code reviews, architecture decisions | | CFO | Analyst | Tracks budgets, monitors token spend, produces cost reports | | CMO | Marketer | Drafts campaigns, manages content calendar, monitors channels | | COO | Operator | Coordinates cross-agent work, manages schedules, unblocks tasks |

• Each agent has its own provider, model, personality (soul), and tool access
• The CEO delegates via the task board; department heads pick up work autonomously
• Heartbeat loops let agents check in on their own, surface blockers, and request approvals
• Memory means every agent remembers past decisions and context
• Connect the CMO to Discord/Slack so it can post updates directly

---

Development Team

A squad of agents mirroring a real