Self-Hosting Guide

Complete guide to self-hosting Clawner on your own infrastructure.

Architecture Overview

Clawner consists of two main components:

Dashboard + Server — A single service that includes:
- WebSocket server for agent connections
- REST API for management
- Next.js dashboard UI
Agent — A lightweight CLI installed on each host

┌──────────────────────────────────────────────────────┐
│                    Your Server                        │
│  ┌─────────────────────────────────────────────────┐ │
│  │              clawner/dashboard                   │ │
│  │  ┌───────────────┐    ┌───────────────┐         │ │
│  │  │   Dashboard   │    │    Server     │         │ │
│  │  │   (Next.js)   │    │  (WebSocket)  │         │ │
│  │  │   Port 3002   │    │  Port 9000    │         │ │
│  │  └───────────────┘    └───────────────┘         │ │
│  │              ▲                ▲                  │ │
│  └──────────────│────────────────│──────────────────┘ │
│                 │                │                    │
│           Nginx/Traefik          │                    │
│                 │                │                    │
└─────────────────│────────────────│────────────────────┘
                  │                │
            ┌─────┴────┐    ┌──────┴──────┐
            │  Users   │    │   Agents    │
            │(browser) │    │ (on hosts)  │
            └──────────┘    └─────────────┘

Prerequisites

A server with Docker or Node.js 20+
A domain pointing to your server
SSL certificate (via Let's Encrypt or Cloudflare)

Deployment Options

Option 1: Docker (Recommended)

# Create data directory
mkdir -p /opt/clawner/data
 
# Run with Docker
docker run -d \
  --name clawner \
  --restart unless-stopped \
  -p 9000:9000 \
  -p 3002:3002 \
  -v /opt/clawner/data:/app/data \
  -e CLAWNER_PASSWORD=your-secure-password \
  -e CLAWNER_JWT_SECRET=$(openssl rand -hex 32) \
  ghcr.io/clawner/dashboard:latest

Option 2: Docker Compose

# docker-compose.yml
version: '3.8'
 
services:
  clawner:
    image: ghcr.io/clawner/dashboard:latest
    container_name: clawner
    restart: unless-stopped
    ports:
      - "9000:9000"
      - "3002:3002"
    environment:
      - CLAWNER_PASSWORD=${CLAWNER_PASSWORD:?Set CLAWNER_PASSWORD}
      - CLAWNER_JWT_SECRET=${CLAWNER_JWT_SECRET}
    volumes:
      - ./data:/app/data
 
networks:
  default:
    name: clawner

# .env
CLAWNER_PASSWORD=your-secure-password
CLAWNER_JWT_SECRET=your-random-secret

Option 3: From Source

git clone https://github.com/clawner/dashboard.git
cd dashboard
npm install
npm run build
 
# Set environment
export CLAWNER_PASSWORD=your-secure-password
export CLAWNER_JWT_SECRET=$(openssl rand -hex 32)
 
# Start
npm start

SSL Configuration

Cloudflare (Easiest)

Add your domain to Cloudflare
Set SSL mode to "Flexible" or "Full"
Cloudflare handles HTTPS automatically

Let's Encrypt + Nginx

# Install certbot
sudo apt install certbot python3-certbot-nginx
 
# Get certificate
sudo certbot --nginx -d clawner.example.com

Nginx config:

server {
    listen 443 ssl http2;
    server_name clawner.example.com;
 
    ssl_certificate /etc/letsencrypt/live/clawner.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/clawner.example.com/privkey.pem;
 
    # Dashboard
    location / {
        proxy_pass http://localhost:3002;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
    }
 
    # API + WebSocket
    location ~ ^/(ws|api|hosts|invite|health) {
        proxy_pass http://localhost:9000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 86400;
    }
}

Security Hardening

Firewall

# UFW
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

Fail2ban

sudo apt install fail2ban

Change Default Password

Always set a strong CLAWNER_PASSWORD:

export CLAWNER_PASSWORD=$(openssl rand -base64 24)
echo "Password: $CLAWNER_PASSWORD"

Backup & Restore

Backup

# Stop container
docker stop clawner
 
# Backup data
tar -czvf clawner-backup-$(date +%Y%m%d).tar.gz /opt/clawner/data
 
# Restart
docker start clawner

Restore

docker stop clawner
tar -xzvf clawner-backup-YYYYMMDD.tar.gz -C /
docker start clawner

Monitoring

Health Check

curl https://your-domain.com/health

Prometheus (Optional)

Metrics endpoint coming in future release.

Updating

# Docker
docker pull ghcr.io/clawner/dashboard:latest
docker stop clawner
docker rm clawner
# Re-run the docker run command
 
# Docker Compose
docker-compose pull
docker-compose up -d

Troubleshooting

Dashboard not loading

Check if both ports are accessible
Verify nginx/traefik is routing correctly
Check logs: docker logs clawner

Agents not connecting

Ensure port 9000 is accessible
Check WebSocket upgrade is working
Verify SSL certificate is valid

Authentication errors

Regenerate JWT secret
Clear browser cache
Check password is set correctly

Commands