Skip to main content

​
Installation

SimpleClaw requires Node.js 22 or higher. Follow the platform-specific instructions below.
Check your Node version with node --version. If you need to upgrade, visit nodejs.org.

​
Prerequisites

  • Node.js ≥ 22
  • npm, pnpm, or bun package manager
  • macOS, Linux, or Windows (WSL2 strongly recommended for Windows)
The fastest way to install SimpleClaw is via npm: 
npm install -g simpleclaw@latest
After installation, run the onboarding wizard: 
simpleclaw onboard --install-daemon
The wizard will:
  • Configure the gateway
  • Set up your workspace
  • Install the daemon service (launchd on macOS, systemd on Linux)
  • Guide you through channel setup
  • Configure model providers

​
Install from Source

For development or to run the latest code:
1

Clone the repository

git clone https://github.com/asundar43/simpleclaw.git
cd simpleclaw
2

Install dependencies

Prefer pnpm for builds from source:
pnpm install
3

Build the UI and core

pnpm ui:build  # auto-installs UI deps on first run
pnpm build
4

Run the onboarding wizard

pnpm simpleclaw onboard --install-daemon
pnpm simpleclaw ... runs TypeScript directly via tsx. The pnpm build command produces dist/ for running via Node or the packaged simpleclaw binary.

​
Platform-Specific Notes

​
macOS

  • The onboarding wizard can install a launchd user service to keep the gateway running
  • The macOS app provides a menu bar interface with voice wake and canvas
  • Screen recording and accessibility permissions may be required for some features

​
Linux

  • The wizard can install a systemd user service
  • SimpleClaw works great on small Linux instances for remote gateway hosting
  • Device nodes (macOS/iOS/Android) can connect for device-local actions

​
Windows

  • WSL2 is strongly recommended for the best experience
  • Native Windows support is limited; use WSL2 with Ubuntu or Debian
  • Install Node.js inside WSL2, not on Windows directly

​
Verification

After installation, verify SimpleClaw is working:
1

Check installation

simpleclaw --version
You should see the version number (e.g., 2026.3.2).
2

Check gateway status

If you installed the daemon:
simpleclaw gateway status
You should see the gateway running on port 18789.
3

Open the Control UI

simpleclaw dashboard
This opens http://127.0.0.1:18789/ in your browser.
If the Control UI loads, your gateway is ready to use!

​
Manual Gateway Start

If you didn’t install the daemon or want to run the gateway manually: 
simpleclaw gateway --port 18789 --verbose
For development with auto-reload: 
pnpm gateway:watch

​
Development Channels

SimpleClaw follows semantic versioning with multiple release channels:
  • stable: Tagged releases (vYYYY.M.D), npm dist-tag latest
  • beta: Prerelease tags (vYYYY.M.D-beta.N), npm dist-tag beta
  • dev: Moving head of main, npm dist-tag dev (when published)
Switch channels: 
simpleclaw update --channel stable|beta|dev

​
Troubleshooting

​
Node version too old

SimpleClaw requires Node 22+. Upgrade via nvm or nodejs.org.

​
Permission denied errors

If global installation fails, try: 
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH
Then re-run the install command.

​
Gateway won’t start

Run the diagnostic tool: 
simpleclaw doctor
This checks for configuration issues, permissions, and conflicts.

​
Next Steps

Quickstart

Get your first chat working in under 5 minutes

Configuration

Configure models, channels, and routing

Add Channels

Connect WhatsApp, Telegram, Discord, and more

Security Setup

Configure DM pairing and allowlists

Build docs developers (and LLMs) love

Get started for freeTalk to us