Documentation

Everything you need to install, configure, and run SquidClaw.

Installation

SquidClaw runs on Linux, macOS, and Windows. Choose your platform:

Linux 🐧 Ubuntu / Debian / Fedora / Arch

One-line install — handles Node.js, dependencies, everything:

curl -fsSL https://squidclaw.dev/hatch | bashbash

This will:

Install Node.js 22+ if not present
Install SquidClaw globally via npm
Run the onboarding wizard

💡 Tested on Ubuntu 22.04+, Debian 12+, Fedora 38+, Arch Linux. Works on Raspberry Pi too.

Manual install

# Install Node.js 22+
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash -
sudo apt-get install -y nodejs

# Install SquidClaw
npm install -g squidclaw

# Run
squidclawbash

macOS 🍎 Intel & Apple Silicon

One-line install:

curl -fsSL https://squidclaw.dev/hatch | bashterminal

Or with Homebrew:

# Install Node.js
brew install node@22

# Install SquidClaw
npm install -g squidclaw

# Run
squidclawterminal

💡 Works on both Intel and Apple Silicon Macs. Requires macOS 13+.

Windows 🪟 PowerShell

Run in PowerShell (as Administrator):

iwr -useb https://squidclaw.dev/hatch.ps1 | iexPowerShell

Or manually:

# Install Node.js 22+ from https://nodejs.org
# Then in PowerShell:

npm install -g squidclaw

# Run
squidclawPowerShell

⚠️ Use PowerShell, not CMD. WSL (Windows Subsystem for Linux) also works — use the Linux instructions.

npm 📦 Any platform

If you already have Node.js 22+:

# Install globally
npm install -g squidclaw

# Or run without installing
npx squidclawany platform

🦑 npx squidclaw is the fastest way. No global install needed.

Quick Start

Install

npx squidclaw

First run auto-detects missing config and launches the setup wizard.

Add your AI key

The wizard will ask for an API key. Supported providers:

# Set via environment variable
export ANTHROPIC_API_KEY=sk-ant-...
# or
export OPENAI_API_KEY=sk-...
# or
export GOOGLE_API_KEY=AI...

Connect a channel

# Telegram
squidclaw channels add telegram

# WhatsApp (scan QR code)
squidclaw channels login whatsapp

# Discord
squidclaw channels add discord

Start the agent

squidclaw

That's it. Your AI agent is live. Send it a message. 🦑

Environment Variables

Variable	Description
ANTHROPIC_API_KEY	Anthropic (Claude) API key
OPENAI_API_KEY	OpenAI (GPT) API key
GOOGLE_API_KEY	Google (Gemini) API key
SQUIDCLAW_STATE_DIR	Override state directory (default: ~/.squidclaw)
SQUIDCLAW_CONFIG_PATH	Override config file path
SQUIDCLAW_GATEWAY_TOKEN	Gateway authentication token
SQUIDCLAW_HOME	Override home directory for path resolution
SQUIDCLAW_LOG_LEVEL	Log level (silent\|error\|warn\|info\|debug\|trace)

CLI Commands

All commands follow the pattern: squidclaw <command> [subcommand] [options]

🌐 Gateway

Command	Description
squidclaw	Smart start — no config → setup, config exists → start gateway
squidclaw gateway run	Run gateway in foreground
squidclaw gateway start	Start as background service
squidclaw gateway stop	Stop the gateway service
squidclaw gateway restart	Restart the gateway
squidclaw gateway status	Show service status + health
squidclaw gateway install	Install as system service (systemd/launchd)
squidclaw gateway health	Fetch gateway health
squidclaw gateway probe	Full reachability + discovery check

🔧 Setup & Config

Command	Description
squidclaw setup	Initialize config and workspace
squidclaw onboard	Interactive onboarding wizard
squidclaw configure	Interactive setup for credentials, channels, agent
squidclaw config get <key>	Get a config value
squidclaw config set <key> <val>	Set a config value
squidclaw config unset <key>	Remove a config key
squidclaw doctor	Health checks + auto-fix
squidclaw doctor --fix	Apply all suggested fixes
squidclaw reset	Reset local config/state
squidclaw uninstall	Remove gateway service + data

💬 Channels

Command	Description
squidclaw channels list	List configured channels
squidclaw channels status	Show connection status per channel
squidclaw channels add <type>	Add a new channel (telegram, discord, etc.)
squidclaw channels login	Link WhatsApp (QR scan)
squidclaw channels remove <id>	Remove a channel
squidclaw message send	Send a message via channel
squidclaw directory	Lookup contacts and groups

🤖 Agents & Sessions

Command	Description
squidclaw agents list	List configured agents
squidclaw agents add	Create a new agent
squidclaw agents delete <id>	Remove an agent
squidclaw agent	Run one agent turn via gateway
squidclaw sessions	List conversation sessions
squidclaw status	Show channel health + recent sessions

🧠 Models

Command	Description
squidclaw models list	List available models
squidclaw models scan	Auto-discover models from API keys
squidclaw models set <model>	Set default model
squidclaw models status	Show current model config
squidclaw models auth add	Add API key for a provider

⏰ Automation

Command	Description
squidclaw cron list	List scheduled jobs
squidclaw cron add	Create a cron job
squidclaw cron rm <id>	Remove a cron job
squidclaw skills list	List available skills
squidclaw skills info <name>	Show skill details
squidclaw memory search <q>	Search memory files
squidclaw hooks list	List internal hooks

🔒 Security & System

Command	Description
squidclaw security audit	Run security audit
squidclaw secrets reload	Hot-reload secrets
squidclaw system event	Send system event to gateway
squidclaw system heartbeat	Manage heartbeat
squidclaw logs	Tail gateway logs
squidclaw update	Update SquidClaw
squidclaw dashboard	Open Control UI in browser
squidclaw tui	Terminal chat UI

🌐 Advanced

Command	Description
squidclaw browser start	Start headless browser
squidclaw sandbox list	List sandbox containers
squidclaw nodes list	List paired devices
squidclaw plugins list	List installed plugins
squidclaw plugins install <pkg>	Install a plugin
squidclaw webhooks	Webhook management
squidclaw dns	DNS discovery helpers
squidclaw completion	Generate shell completion script

Global Flags

Flag	Description
--dev	Isolate state under ~/.squidclaw-dev, use port 19001
--profile <name>	Named profile (isolates state + config)
--no-color	Disable ANSI colors
--log-level <level>	Override log level
--version, -V	Print version
--help, -h	Show help

Config File

Config lives at ~/.squidclaw/squidclaw.json. Example:

{
  "agents": {
    "defaults": {
      "workspace": "~/.squidclaw/workspace",
      "model": {
        "primary": "anthropic/claude-sonnet-4-20250514"
      }
    }
  },
  "channels": {
    "telegram": {
      "botToken": "123456:ABC...",
      "allowFrom": ["your-telegram-id"]
    },
    "whatsapp": {
      "enabled": true
    }
  },
  "gateway": {
    "mode": "local",
    "port": 18789
  }
}squidclaw.json