Installation Guide

This guide covers multiple ways to install and run profClaw.

npm Install (Recommended)
Docker Installation
One-Line Install
From Source (Development)
Production Deployment
Environment Configuration
First-Time Setup
Troubleshooting
FAQ

npm Install (Recommended)

Requires Node 22+.

Install the package globally:

npm install -g profclaw@latest
# or: pnpm add -g profclaw@latest

Run the setup wizard (configures AI provider, admin account, and registration mode):

profclaw setup

Start the server:

profclaw serve

The server starts at http://localhost:3000. Verify it works:

curl http://localhost:3000/health
# {"status":"ok","timestamp":"..."}

One-Line Install

Auto-detects npm/pnpm or Docker and installs accordingly:

Run the install script:

curl -fsSL https://raw.githubusercontent.com/profclaw/profclaw/main/install.sh | bash

Follow the prompts, then start the server as directed by the script output.
Verify the server is up:

curl http://localhost:3000/health
# {"status":"ok","timestamp":"..."}

From Source (Development)

Prerequisites

Node.js 22+ — Download
pnpm — installed via corepack
Redis — for the job queue (optional in development)

Steps

Clone and install dependencies:

git clone https://github.com/profclaw/profclaw.git
cd profclaw

corepack enable
pnpm install

Configure your environment:

cp .env.example .env
# Edit .env — add at least one AI provider key

Start the dev server:

pnpm dev

The server starts at http://localhost:3000 with hot reload enabled. Verify it works:

curl http://localhost:3000/health
# {"status":"ok","timestamp":"..."}

Docker Installation

Using Docker Compose (Recommended)

Clone the repository:

git clone https://github.com/profclaw/profclaw.git
cd profclaw

Create and configure your environment file:

cp .env.example .env
# Edit .env with your API keys

Start all services:

docker compose up -d

Verify the server is up:

curl http://localhost:3000/health
# {"status":"ok","timestamp":"..."}

Other useful commands:

# View logs
docker compose logs -f profclaw

# Stop services
docker compose down

Available Profiles

# Default: profClaw + Redis
docker compose up -d

# With local AI (Ollama)
docker compose --profile ai up -d

# With monitoring (Prometheus + Grafana)
docker compose --profile monitoring up -d

# With development tools (Redis Commander)
docker compose --profile tools up -d

# All profiles
docker compose --profile ai --profile monitoring --profile tools up -d

Using Pre-built Image

Pull the image:

docker pull ghcr.io/profclaw/profclaw:latest

Run the container (requires Redis):

docker run -d \
  --name profclaw \
  -p 3000:3000 \
  -e REDIS_URL=redis://your-redis-host:6379 \
  -e ANTHROPIC_API_KEY=sk-ant-xxx \
  --env-file .env \
  ghcr.io/profclaw/profclaw:latest

Verify it works:

curl http://localhost:3000/health
# {"status":"ok","timestamp":"..."}

Production Deployment

Requirements

Redis — required for the job queue
Persistent storage — for the SQLite database
Reverse proxy — Nginx or Cloudflare for HTTPS

Docker Compose Production

Set environment variables in .env:

NODE_ENV=production
PORT=3000
REDIS_URL=redis://redis:6379
CORS_ORIGIN=https://your-domain.com

# AI Provider (at least one required)
ANTHROPIC_API_KEY=sk-ant-xxx

# Storage
STORAGE_TIER=libsql
LIBSQL_URL=libsql://your-db.turso.io
LIBSQL_AUTH_TOKEN=xxx

Deploy:

docker compose -f docker-compose.yml up -d

Verify the deployment:

curl http://localhost:3000/health
# {"status":"ok","timestamp":"..."}

Docker Compose includes automatic health checks with restart on failure.

Cloudflare Tunnel

For secure exposure without port forwarding:

Install cloudflared:

brew install cloudflare/cloudflare/cloudflared  # macOS
# or download from https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/installation

Authenticate and create a tunnel:

cloudflared tunnel login
cloudflared tunnel create profclaw

Create a config file (~/.cloudflared/config.yml):

tunnel: <TUNNEL_ID>
credentials-file: /root/.cloudflared/<TUNNEL_ID>.json
ingress:
  - hostname: profclaw.yourdomain.com
    service: http://localhost:3000
  - service: http_status:404

Start the tunnel:

cloudflared tunnel run profclaw

In the Cloudflare dashboard, create a DNS CNAME record pointing profclaw.yourdomain.com to <TUNNEL_ID>.cfargotunnel.com.

Environment Configuration

Required Variables

Variable	Description
At least one AI provider key	`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY`, or `GROQ_API_KEY`

Recommended Variables

Variable	Default	Description
`PORT`	`3000`	HTTP server port
`NODE_ENV`	`development`	Environment mode
`REDIS_URL`	—	Redis URL for job queue
`STORAGE_TIER`	`file`	Storage backend: `memory`, `file`, `libsql`

AI Providers

Configure at least one:

# Anthropic Claude
ANTHROPIC_API_KEY=sk-ant-xxx

# OpenAI
OPENAI_API_KEY=sk-xxx

# Google Gemini
GOOGLE_GENERATIVE_AI_API_KEY=xxx

# Groq (fast inference)
GROQ_API_KEY=gsk_xxx

# Ollama (local models, no API key needed)
OLLAMA_BASE_URL=http://localhost:11434

Integrations

# GitHub
GITHUB_TOKEN=ghp_xxx
GITHUB_CLIENT_ID=xxx
GITHUB_CLIENT_SECRET=xxx
GITHUB_WEBHOOK_SECRET=xxx

# Jira
JIRA_CLIENT_ID=xxx
JIRA_CLIENT_SECRET=xxx

# Linear
LINEAR_API_KEY=lin_api_xxx

# Slack
SLACK_BOT_TOKEN=xoxb-xxx
SLACK_SIGNING_SECRET=xxx

# Discord
DISCORD_BOT_TOKEN=xxx
DISCORD_APPLICATION_ID=xxx
DISCORD_PUBLIC_KEY=xxx

# Telegram
TELEGRAM_BOT_TOKEN=xxx

# WhatsApp
WHATSAPP_ACCESS_TOKEN=xxx
WHATSAPP_PHONE_NUMBER_ID=xxx

See .env.example for the complete list.

First-Time Setup

After starting the server, create your admin account using the setup wizard.

Option 1: Docker CLI (Recommended)

# Interactive setup wizard
docker exec -it profclaw profclaw setup

# Or non-interactive (CI/automation)
docker exec profclaw profclaw setup \
  --non-interactive \
  --admin-email admin@profclaw.dev \
  --admin-password YourSecurePass123 \
  --admin-name "Admin" \
  --ai-provider skip \
  --registration-mode invite

The wizard configures:

AI provider (Anthropic, OpenAI, Ollama, or skip)
Admin account with recovery codes
Registration mode (invite-only or open)
GitHub OAuth (optional)

Option 2: Local CLI

# If running via Node.js
pnpm profclaw setup

# Or individual commands:
pnpm profclaw auth create-admin --email admin@example.com --name "Admin"
pnpm profclaw auth set-mode invite

Option 3: Web UI

Visit http://localhost:3000/setup and follow the on-screen wizard.

Low-Memory Devices (Raspberry Pi Zero, 512MB VPS)

On devices with 512MB RAM or less, npm install -g profclaw will get killed by the OOM killer before it finishes. Three options:

Option 1: Docker pico image (recommended)

The pico image is pre-built and skips npm install entirely. It runs the agent engine, tools, and one chat channel in roughly 140MB RAM with no UI and no Redis.

Pull and run the pico image:

docker run -d \
  --name profclaw \
  -p 3000:3000 \
  -e PROFCLAW_MODE=pico \
  -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
  -v profclaw-data:/app/data \
  ghcr.io/profclaw/profclaw:pico

Or build locally from Dockerfile.pico:

docker build -f Dockerfile.pico -t profclaw:pico .
docker run -d --name profclaw -p 3000:3000 -e PROFCLAW_MODE=pico profclaw:pico

Verify it works:

curl http://localhost:3000/health
# {"status":"ok","timestamp":"..."}

Option 2: Add swap before npm install

Extend swap to 1GB so npm has enough memory:

sudo dphys-swapfile swapoff
sudo sed -i 's/CONF_SWAPSIZE=.*/CONF_SWAPSIZE=1024/' /etc/dphys-swapfile
sudo dphys-swapfile setup
sudo dphys-swapfile swapon

Install and start in pico mode:

npm install -g profclaw@latest

# Start in pico mode
PROFCLAW_MODE=pico profclaw serve

Verify it works:

curl http://localhost:3000/health
# {"status":"ok","timestamp":"..."}

Option 3: Cross-install from another machine

Install on a machine with more RAM:

npm install -g profclaw@latest
INSTALL_PATH=$(npm root -g)/profclaw

Copy to the target device and run:

scp -r $INSTALL_PATH pi@raspberry.local:~/profclaw
ssh pi@raspberry.local "cd ~/profclaw && PROFCLAW_MODE=pico node dist/server.js"

Hardware requirements by mode

Mode	Min RAM	Swap needed?	What you get
pico	256MB	Yes (512MB+)	Agent + tools + 1 channel, no UI
mini	512MB	Recommended	Dashboard, integrations, 3 channels
pro	1GB+	No	Everything including Redis, browser tools

Troubleshooting

Redis Connection Issues

# Check Redis is running
redis-cli ping

# In Docker, check network connectivity
docker network inspect profclaw-network

Database Errors

# File-based storage (development)
ls -la data/

# Reset database
rm -rf data/*.db
pnpm dev

AI Provider Errors

Check that your API keys are valid:

# Test Anthropic
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-3-haiku-20240307","max_tokens":1,"messages":[{"role":"user","content":"Hi"}]}'

Port Already in Use

# Find which process is using port 3000
lsof -i :3000 | grep LISTEN

# Kill it by PID
kill -9 <PID>

Docker Build Issues

# Clean build
docker compose build --no-cache

# Check logs
docker compose logs profclaw

Upgrading

Docker

# Pull latest image
docker compose pull

# Restart with new image
docker compose up -d

Manual Installation

git pull
pnpm install
pnpm build
pnpm start

FAQ

npm install gets killed on low-memory devices The OOM killer terminates npm install when RAM runs out. Two fixes: add 1GB of swap before installing (see Option 2 in the low-memory guide), or skip npm install entirely by using the Docker pico image (see Option 1). Port 3000 is already in use Find what is listening on it:

lsof -i :3000 | grep LISTEN

Then kill that process by PID, or start profClaw on a different port by setting PORT=3001 in your .env. No AI provider configured Set at least one of these environment variables before starting the server:

ANTHROPIC_API_KEY=sk-ant-xxx
OPENAI_API_KEY=sk-xxx
GOOGLE_GENERATIVE_AI_API_KEY=xxx
OLLAMA_BASE_URL=http://localhost:11434

See Environment Configuration for the full list. How do I use a local AI model?

Install Ollama on your machine.
Pull a model:

ollama pull llama3.2

Set OLLAMA_BASE_URL in your .env:

OLLAMA_BASE_URL=http://localhost:11434

Restart profClaw. The Ollama provider shows up automatically in the model list.

If you are running profClaw inside Docker, use http://host.docker.internal:11434 instead of localhost.

Documentation Index

​Installation Guide

​Table of Contents

​npm Install (Recommended)

​One-Line Install

​From Source (Development)

​Prerequisites

​Steps

​Docker Installation

​Using Docker Compose (Recommended)

​Available Profiles

​Using Pre-built Image

​Production Deployment

​Requirements

​Docker Compose Production

​Cloudflare Tunnel

​Environment Configuration

​Required Variables

​Recommended Variables

​AI Providers

​Integrations

​First-Time Setup

​Option 1: Docker CLI (Recommended)

​Option 2: Local CLI

​Option 3: Web UI

​Low-Memory Devices (Raspberry Pi Zero, 512MB VPS)

​Option 1: Docker pico image (recommended)

​Option 2: Add swap before npm install

​Option 3: Cross-install from another machine

​Hardware requirements by mode

​Troubleshooting

​Redis Connection Issues

​Database Errors

​AI Provider Errors

​Port Already in Use

​Docker Build Issues

​Upgrading

​Docker

​Manual Installation

​FAQ

​Getting Help