Getting Started

Prerequisites

Node.js 22.6+
One of: npm 10+, pnpm, Yarn, or Bun
Claude Code CLI (optional) — for the claude-cli provider. Install guide
OpenAI Codex CLI (optional) — for the codex-cli provider. Install guide
OpenCode CLI (optional) — for the opencode-cli provider. Install guide

Installation

SwarmClaw is published to the npm registry once and can be installed with npm, pnpm, yarn, or bun. End users do not need a separate signup for each package manager.

One-off run

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

Install script

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

To pin a specific release:

SWARMCLAW_VERSION=v0.8.7 curl -fsSL https://swarmclaw.ai/install.sh | bash

To update later:

npm update -g @swarmclawai/swarmclaw
pnpm update -g @swarmclawai/swarmclaw
yarn global add @swarmclawai/swarmclaw@latest
bun add -g @swarmclawai/swarmclaw@latest
# or, if installed via script:
cd ~/swarmclaw
npm run update:easy

First-Time Setup

On first launch, SwarmClaw generates an access key and prints it to the terminal:

==================================================
  ACCESS KEY: a1b2c3d4e5f6...
  Use this key to connect from the browser.
==================================================

The key is saved to .env.local automatically.

Open http://localhost:3456 in your browser. The first-time setup screen shows your key with a copy button. Copy it, paste it in, and set your name.

Setup Wizard

After entering your name, the setup wizard walks you through a starter workflow for your first workspace:

Choose an onboarding path — Quick Start, Intent Guided, or Custom Setup.
Pick a starter kit — choose a suggested starter workspace or begin blank.
Add providers — connect one or more providers, then reuse them across starter agents.
Deploy OpenClaw when needed — OpenClaw onboarding now includes Smart Deploy for official local bring-up, preconfigured remote bundles for Hetzner, DigitalOcean, Vultr, Linode, Lightsail, GCP, Azure, OCI, generic Ubuntu VPS hosts, plus Render/Fly.io/Railway templates and in-house SSH deploy.
Choose safer defaults — OpenClaw onboarding now exposes use-case templates (local-dev, single-vps, private-tailnet, browser-heavy, team-control) and exposure presets (tailscale, ssh-tunnel, caddy, nginx, private-lan) before the gateway is saved.
Verify and save OpenClaw when needed — OpenClaw setups require a successful gateway connection check before continuing. SwarmClaw treats websocket gateway reachability as the primary health signal and shows optional HTTP /v1 compatibility warnings separately. If the device is pending approval, approve it from the gateway Nodes view and re-run the check.
Finish with starter agents — review the created agents and jump straight into chat.

You can add multiple providers in one setup session, map them onto different starter agents, and skip back out to manual configuration at any point from the sidebar. If you skip OpenClaw deployment during onboarding, the same Smart Deploy and lifecycle controls are available later from Providers -> OpenClaw Gateways and inside the gateway editor.

You can also complete setup from the CLI by running swarmclaw setup init for an interactive walkthrough, or pass flags directly (e.g. --provider openai --api-key <key>).

Accessing from Mobile

SwarmClaw binds to 0.0.0.0, so any device on your local network can reach it. Find your machine's IP and open:

http://192.168.x.x:3456

Enter the same access key from the terminal.

Next Steps

Configuration — Environment variables and data storage
Providers — Connect your LLM providers
OpenClaw Setup — Local, VPS, and hosted OpenClaw deployment options
Agents — Build custom agents
Deployment — Deploy to a VPS with pm2, Docker, or systemd