SwarmClaw: one npm package carrying an Electron app and a Next.js server
Open-source self-hosted AI agent runtime and multi-agent framework for autonomous agent swarms. Agent memory, MCP tools, schedules, delegation, and 23+ LLM providers (Claude, GPT, Gemini, OpenRouter, Ollama). A practical Claude Code and LangChain alternative.
At a glance
- What is it?
- swarmclawai/swarmclaw is a self-hosted agent runtime with durable memory, MCP tools, schedules and delegation across 23 or more providers, distributed as a single package whose declared entry point is the Electron main process while its container image runs the Next.js standalone server.
- Who is it for?
- SwarmClaw has done the unglamorous work that agent platforms tend to skip. The 1.9.39 notes are a list of failure modes someone hit in production: dead-lettered orphans, delivery status written back onto the schedule, a credential preflight that fails before the request rather than on a 401, a migration that rebinds old workspace roots without touching the ones you set deliberately.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 138 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- swarmclawai/swarmclaw712 ★ · +43
| Repository | 2026-09-11 | 2026-11-15 |
|---|---|---|
| swarmclawai/swarmclaw | 669 | 712 |
43 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The declared entry point is Electron and the container runs Next.js
`package.json` is named `@swarmclawai/swarmclaw` at version `1.9.40`, and its `main` field points at `electron-dist/main.js`. The Dockerfile tells a different story: it builds with `SWARMCLAW_BUILD_MODE=1 npm run build:ci`, then copies `.next/standalone`, `.next/static`, `public/`, `node_modules/`, and `package.json` into a runner stage whose command is `node server.js`. So the same published tree carries an Electron main process and a Next.js standalone server, and the `bin` field maps `swarmclaw` to `bin/swarmclaw.js` to start the latter. The `files` array is worth reading closely too: it ships `bin/`, `skills/`, `src/`, `public/`, `Dockerfile.sandbox-browser`, seven individual scripts, and three config files, with an explicit `!src/**/.env*` exclusion. Neither `electron/` nor an `electron-dist/` entry appears in that list.
Node 22.6 is the floor and the .nvmrc is what CI uses
The requirements are short and specific. Node.js 22.6 or newer, with `nvm use` picking up the repository's `.nvmrc`, which the README says matches CI, and npm 10 or another supported package manager. The `engines` field agrees, at `node >=22.6.0`. Docker Desktop is described as recommended rather than required, and only for sandbox browser execution, which is the one feature that needs a container around it. Then there is a fourth requirement that is easy to miss: provider CLIs, if you want delegated CLI backends. That covers Claude Code, Codex, OpenCode, Gemini, Copilot, Factory Droid, Cursor Agent, Qwen Code, and Goose, and it means an installation can be complete and still be missing every capability you wanted if you skipped it.
Three installs, and the desktop one ships unsigned when Apple credentials are absent
The global route is one line, and it is the same for four package managers: `npm i -g @swarmclawai/swarmclaw`, or the yarn, pnpm, and bun equivalents, followed by running `swarmclaw`, which starts the server on `http://localhost:3456`. From a clone it is `nvm use` and then `npm run quickstart`, which installs dependencies, prepares local config and runtime state, and starts the app. The container route creates a `data` directory and an empty `.env.local` before `docker compose up -d --build`. The desktop route is the messiest. It is a one-click installer for macOS on Apple Silicon and Intel, Windows, and Linux as AppImage and `.deb`, and the release workflow only does Developer ID signing and notarization when Apple credentials are configured. Unsigned fallback releases publish a `.zip` and skip the `.dmg` specifically to avoid a damaged-image path, so a `.zip` in the downloads list is a signal rather than a mistake.
Quarantine flags and Gatekeeper are documented as a normal step
The instructions for an unsigned or ad-hoc signed build are part of the quick start rather than a troubleshooting appendix. On macOS, right-click the app in Finder, choose Open, then Open again, to get past Gatekeeper. If macOS instead reports that SwarmClaw is damaged and cannot be opened, which the README calls common when a downloaded app was quarantined by Safari, the fix is a shell command rather than a settings change:
xattr -dr com.apple.quarantine /Applications/SwarmClaw.appWindows gets the SmartScreen equivalent, clicking More info and then Run anyway, and Linux AppImage builds need `chmod +x` on the downloaded file. Two consequences follow for anyone automating this. The signed path depends on credentials held by the release workflow rather than by anything in the repository, so signing status varies between releases. And the desktop build stores its data in the OS application-data directory rather than in your checkout, at `~/Library/Application Support/SwarmClaw`, `%APPDATA%\SwarmClaw`, or `~/.config/SwarmClaw`, explicitly separate from any CLI or Docker install. One machine, three installs, three separate state locations.
The v1.9.39 release is a list of ways scheduled runs used to fail silently
The most informative section of the documentation is the changelog for the scheduled-run reliability release, and every item in it is a failure someone had to diagnose. Scheduled runs on API-key providers now fail fast with an actionable error when no credential resolves, instead of dying on a 401 deep inside execution. Runs that produce no text, no tool calls, and no error are classified as empty and fail with a provider-configuration message rather than a generic validation failure. Every scheduled run writes `lastDeliveryStatus` and `lastDeliveryError` back to its schedule, so a failure is visible without digging through task records. Orphan recovery now recovers each orphaned task once rather than re-logging it on every tick, and dead-letters tasks that repeatedly return to the queue without ever starting. Follow-up sends go through a connector outbox with task and schedule linkage, retry with backoff, and dedupe per run.
The workspace root moved once, and now the code migrates it for you
That same release contains a migration worth understanding before you have state to lose. Scheduled reruns and reused schedule sessions that had pinned a pre-migration workspace root, an older path such as `~/.swarmclaw/workspace`, are now rebound automatically to the current `WORKSPACE_DIR`. The guarantee is specific in one direction and it matters: intentional custom working directories are never touched. That is the right shape for a migration, since the failure mode of guessing wrong is an agent pointed at the wrong tree. The environment surface around it is a set of directories rather than a database URL: state in the container lives in `./data` mounted at `/app/data`, credentials come from an optional `./.env.local` declared with `required: false`, and the desktop app uses the OS application-data path instead. Three installs, three state locations, and one migration that assumes it can recognise an old one.
The healthcheck calls a real endpoint, which is rarer than it should be
The compose file defines one service built from the local context and tagged `ghcr.io/swarmclawai/swarmclaw:latest`, publishing ports 3456 and 3457, mounting `./data:/app/data`, and reading `./.env.local` as an optional env file. The healthcheck is worth quoting because its shape matters:
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3456/api/healthz"]It shells out to `curl -f` against a real HTTP path, every 30 seconds, with a 5 second timeout, 3 retries, and a 10 second start period, and the service restarts `unless-stopped`. A process that answers `/api/healthz` with a non-2xx is reported unhealthy, which is more than a command that exits zero unconditionally can do. The image sets `ENV PORT=3456` and `ENV HOSTNAME=0.0.0.0`, so the server inside the container binds every interface, which matters if you publish 3457 without deciding who should reach it.
The image retries npm ci three times and ships the whole node_modules
The build stage is `node:22-slim` with `git`, `python3`, `make`, and `g++` installed, the compiler toolchain being for `better-sqlite3`. Dependency installation is wrapped in a retry loop: `npm ci` is attempted up to three times with `sleep $((attempt * 5))` between failures and an `exit 1` after the third, alongside npm fetch retry settings. The runner stage is a second `node:22-slim` with only `git`, `curl`, and `unzip`, and it copies `/app/node_modules` wholesale from the build stage rather than reinstalling, so the production image carries whatever the build stage resolved, devDependencies included. The `overrides` block in `package.json` is where dependency security is pinned, holding `protobufjs` at `7.5.5` and forcing `form-data` inside `request` to `2.5.5`. Two such overrides on a Next.js and Electron tree is a small number, and they are the ones a consumer inherits without choosing.
Editorial conclusion
SwarmClaw has done the unglamorous work that agent platforms tend to skip. The 1.9.39 notes are a list of failure modes someone hit in production: dead-lettered orphans, delivery status written back onto the schedule, a credential preflight that fails before the request rather than on a 401, a migration that rebinds old workspace roots without touching the ones you set deliberately. That is worth more than another provider integration. Two things to check first. Whether you want the Electron app, the CLI server, or the container, because the package serves all three from one tree and the entry points differ. And whether your state lives where you think: the desktop app writes to the OS app-data directory, the container writes to a mounted `./data`, and the workspace root moved once already, which is why a migration now rebinds it. Read the schedule delivery fields before you trust an unattended send.
Frequently asked questions
What is SwarmClaw and what is it an alternative to?
An open-source, self-hosted AI agent runtime and multi-agent framework. It runs agents and swarms with heartbeats, schedules, delegation, agent memory, runtime skills, and reviewed conversation-to-skill learning, and the project describes itself as a practical alternative to Claude Code and LangChain.
How do I install SwarmClaw and what does it require?
Node.js 22.6 or newer, npm 10 or another supported package manager, and a `.nvmrc` in the repository that matches CI. Install with `npm i -g @swarmclawai/swarmclaw` and run `swarmclaw`, or clone and run `npm run quickstart`. Docker Desktop is recommended for sandbox browser execution.
Which models and CLI backends can SwarmClaw delegate to?
More than 23 providers, including Anthropic, OpenAI, OpenRouter, Gemini, Ollama, DeepSeek, Groq, Together, Mistral, xAI, Fireworks, Nebius, and DeepInfra. It also drives CLI backends such as Claude Code, Codex, OpenCode, Gemini CLI, Copilot, Factory Droid, Cursor Agent, Qwen Code, and Goose, which have to be installed separately.
What port does SwarmClaw serve on and where does it keep data?
The server starts on `http://localhost:3456`, and the compose file also publishes port 3457. The desktop app keeps data in the OS application-data directory, while the container mounts `./data` at `/app/data`, and the two are explicitly separate from any CLI install.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/swarmclawai-swarmclaw)Star history chart for your README
[](https://hysenlabs.com/projects/swarmclawai-swarmclaw)Was this useful?