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

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.3.5 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 starter kit or begin blank.
  3. Add one or more providers.
  4. Deploy or connect OpenClaw when needed.
  5. Review safer defaults for automation, tools, and routing.
  6. Finish with starter agents and go straight into chat.

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