Install on macOS or Linux

• Node.js 20+ (22 recommended)
• npm (comes with Node.js)
• Git + a POSIX shell (zsh/bash)

That's it. No database, no Redis, no extra tooling. The installer will auto-install Node.js if it's missing.

On Windows? See the Windows install guide.

If Homebrew is not installed, install it first:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

brew install git node@22
brew link --overwrite node@22

sudo apt update
sudo apt install -y curl git

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

For non-Debian distributions (Fedora, Arch, etc.), install Node.js 20+ using your package manager or nodejs.org.

node -v   # v20.x or v22.x
npm -v    # 10.x+
git --version

If you already have Node.js 20+, this is the fastest way to get ClawMagic running:

npm install -g clawmagic
clawmagic onboard

That's it. Two commands and you're running. The onboard command walks you through provider setup and agent configuration.

If you prefer the full installer with automatic Node.js setup, service installation, and browser-based onboarding:

curl -fsSL https://clawmagic.ai/install.sh | bash

Or clone and run manually:

git clone https://github.com/clawmagic/clawmagic.git
cd clawmagic
bash scripts/install.sh

Auto-installs Node.js if missing. Clones to ~/clawmagic. Respects CLAWMAGIC_HOME and CLAWMAGIC_BRANCH env vars.

The installer will prompt you to choose:

• 1) Mom Setup (default) — Portal + CLI, ~4 min. Builds all 9 packages and opens onboarding in your browser.
• 2) Quick Install — CLI only, ~2 min. Builds 8 packages (skips web). Onboarding runs in the terminal. Add the portal later with npm run build:web.

Both modes auto-detect Node 22, validate disk space (1GB min), install Playwright, run doctor diagnostics, install a background service (launchd/systemd), and verify /health. Use --dry-run for pre-flight validation. Port conflicts are auto-remapped.

Hosting providers and production deployments can skip the interactive installer entirely. These methods require no build step — pre-built channels ship compiled artifacts ready to run.

The release pipeline (.github/workflows/release.yml) publishes all channels automatically on any v* tag.

# Pull the latest pre-built image (amd64 + arm64)
docker pull ghcr.io/clawmagic/clawmagic:latest

# Run with persistent volumes
docker run -d \
  --name clawmagic \
  -p 18790:18790 \
  -v clawmagic-state:/app/state \
  -v clawmagic-config:/root/.clawmagic \
  ghcr.io/clawmagic/clawmagic:latest

# Available tags: latest, v0.1.0, sha-*

• Multi-platform: linux/amd64 + linux/arm64
• Multi-stage build: uses npm ci, npm prune --omit=dev, and selective COPY for a minimal runtime image
• Volume persistence: mount /app/state and /root/.clawmagic to preserve state and config across restarts
• Portal password: docker-setup.sh auto-generates a portal password. Fails if no secure RNG is available.

# Using the pre-built image (recommended)
docker compose up -d

# Or build locally from source
docker compose up --build -d

# docker-compose.yml includes:
#   - Volume persistence for state/ and ~/.clawmagic/
#   - Commented image: line to switch between local build and pre-built
#   - Port mapping: 18790:18790

The included docker-compose.yml has a commented image: line. Uncomment it and comment out the build: section to switch from local build to the pre-built image from GitHub Container Registry.

• AppArmor profile: docker/apparmor.profile — restricts container filesystem and network access.
• Seccomp profile: docker/seccomp.json — limits system calls available to the container.
• No root required: the Dockerfile runs as a non-root user in production builds.
• Portal password: server enforces a 10-character minimum. Hashed with scrypt. Auto-generated in Docker via scripts/docker-setup.sh.
• Secrets encrypted: credential cache uses AES-256-GCM. No plaintext secrets on disk.
• Localhost-only by default: server binds to 127.0.0.1. Set CLAWMAGIC_ALLOW_REMOTE=true and CLAWMAGIC_HOST=0.0.0.0 to expose to the network (use with TLS termination).

Containers and CI/CD pipelines should use non-interactive onboarding. No browser needed.

# Minimal non-interactive setup
clawmagic onboard --non-interactive --accept-risk --flow quickstart

# Full non-interactive with all options
clawmagic onboard --non-interactive --accept-risk \
  --provider anthropic --model claude-3-sonnet \
  --agent-name "Production Agent" --autonomy balanced \
  --goal "Handle automated tasks" \
  --heartbeat-interval 30m --json

Available flags: --provider, --model, --agent-name, --autonomy, --goal, --flow, --heartbeat-interval, --json.

• /docs/onboarding — walkthrough of the Mom Setup wizard and Quick Install CLI.
• /docs/deployment — production deployment, remote access, and health checks.
• /docs/environment — config files, provider keys, and feature flags.
• /docs/quickstart — get ClawMagic running in about 15 minutes.