Getting Started

Prerequisites

  • Node.js 22.6+
  • One of: npm 10+, pnpm, Yarn, or Bun
  • Docker Desktop (optional, recommended) for browser sandbox and container-backed execution flows
  • Optional provider CLIs if you plan to use CLI-backed agents:
    • Claude Code CLI
    • OpenAI Codex CLI
    • OpenCode CLI
    • Gemini CLI
    • GitHub Copilot CLI
    • Factory Droid CLI
    • Cursor Agent CLI
    • Qwen Code CLI
    • Goose

Installation

SwarmClaw is published once to npm and can be installed with any major Node package manager.

Global install

npm i -g @swarmclawai/swarmclaw
pnpm add -g @swarmclawai/swarmclaw
yarn global add @swarmclawai/swarmclaw
bun add -g @swarmclawai/swarmclaw
swarmclaw

Running swarmclaw with no arguments starts the server on 0.0.0.0:3456.

Global installs run postinstall, rebuild better-sqlite3, and prepare the sandbox browser image when Docker is available. Runtime state defaults to ~/.swarmclaw unless you set SWARMCLAW_HOME.

Local project install

npm i @swarmclawai/swarmclaw
npx swarmclaw

Local installs keep runtime state in <project>/.swarmclaw by default. The same pattern works with pnpm, yarn, or bun using that package manager's exec command.

One-off run

npx @swarmclawai/swarmclaw
pnpm dlx @swarmclawai/swarmclaw
yarn dlx @swarmclawai/swarmclaw
bunx @swarmclawai/swarmclaw

One-off runs use the published package without keeping a project-local install. Runtime state defaults to ~/.swarmclaw unless you set SWARMCLAW_HOME.

Install script

curl -fsSL https://swarmclaw.ai/install.sh | bash
cd ~/swarmclaw
npm run start

The install script clones the latest stable release, installs dependencies, bootstraps the local environment, and prebuilds the production bundle.

To pin a specific release:

SWARMCLAW_VERSION=v1.6.0 curl -fsSL https://swarmclaw.ai/install.sh | bash

To update later:

# Global install
swarmclaw update
npm update -g @swarmclawai/swarmclaw
pnpm update -g @swarmclawai/swarmclaw
yarn global add @swarmclawai/swarmclaw@latest
bun add -g @swarmclawai/swarmclaw@latest

# Local project install
npm update @swarmclawai/swarmclaw
npx swarmclaw

# Install script checkout
cd ~/swarmclaw
npm run update:easy

First-Time Setup

On first launch, SwarmClaw generates an access key and prints it to the terminal. The key is saved to .env.local automatically.

Open http://localhost:3456 in your browser, enter the access key, and complete the setup wizard.

Setup Wizard

The setup wizard walks you through a starter workflow for a fresh workspace:

  1. Choose an onboarding path.
  2. Pick a broad starting shape or begin blank.
  3. Add one or more providers.
  4. Deploy or connect OpenClaw when needed.
  5. Review the starter agents before saving them.
  6. Finish on a launchpad with direct links into chat, protocols, connectors, and usage.

If you skip OpenClaw during onboarding, the same deployment and gateway-management flows remain available later from the provider and gateway surfaces.

You can also complete setup from the CLI:

swarmclaw setup init
swarmclaw setup init --provider openai --api-key "$OPENAI_API_KEY"
swarmclaw setup check-provider --provider ollama --endpoint http://localhost:11434

Accessing from Mobile

SwarmClaw binds to 0.0.0.0, so devices on your local network can reach it:

http://192.168.x.x:3456

Use the same access key from the terminal.

Next Steps