Deployment

Deploy SwarmClaw to a VPS so it's always online — your agents, connectors, and schedules run 24/7.

The simplest approach. SSH into your VPS and run SwarmClaw with pm2 behind a reverse proxy.

Prerequisites

  • Ubuntu 22.04+ or Debian 12+ (any Linux works, commands may differ)
  • Node.js 20+ and npm 10+
  • A domain name (optional, for TLS)

Install Node.js

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -
sudo apt install -y nodejs git build-essential

build-essential is needed for better-sqlite3 native compilation.

Clone and Build

git clone https://github.com/swarmclawai/swarmclaw.git
cd swarmclaw
npm install
npm run build

Run with pm2

pm2 keeps SwarmClaw running and restarts it on crashes or reboots.

sudo npm install -g pm2
pm2 start npm --name swarmclaw -- start
pm2 save
pm2 startup

SwarmClaw is now running on port 3456. Check the logs for your access key:

pm2 logs swarmclaw --lines 20

Reverse Proxy with Caddy

Caddy auto-provisions TLS certificates. Install it and create a config:

sudo apt install -y caddy

Edit /etc/caddy/Caddyfile:

swarmclaw.yourdomain.com {
    reverse_proxy localhost:3456
}

sudo systemctl restart caddy

Your instance is now live at https://swarmclaw.yourdomain.com with automatic HTTPS.

Reverse Proxy with nginx (Alternative)

sudo apt install -y nginx certbot python3-certbot-nginx

Create /etc/nginx/sites-available/swarmclaw:

server {
    listen 80;
    server_name swarmclaw.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:3456;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_read_timeout 86400;
    }
}

sudo ln -s /etc/nginx/sites-available/swarmclaw /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl restart nginx
sudo certbot --nginx -d swarmclaw.yourdomain.com

Firewall

Only expose ports 80/443 publicly. Never expose 3456 directly.

sudo ufw allow OpenSSH
sudo ufw allow 80
sudo ufw allow 443
sudo ufw enable

Updating

SwarmClaw has a built-in update checker. When updates are available, a banner appears in the sidebar with a one-click update button.

To update manually:

cd swarmclaw
git pull origin main
npm install
npm run build
pm2 restart swarmclaw

Your data in data/ and .env.local is untouched — only source code is updated.

Option 2: Docker

Prerequisites

  • Docker and Docker Compose installed on your VPS

Quick Start

git clone https://github.com/swarmclawai/swarmclaw.git
cd swarmclaw
docker compose up -d

This builds the image, mounts data/ and .env.local as volumes, and runs on port 3456.

Check Logs

docker compose logs -f

Look for the access key on first launch.

Updating

git pull origin main
docker compose up -d --build

With a Reverse Proxy

Same Caddy or nginx config as Option 1 — point it at localhost:3456.

Custom Port

Edit docker-compose.yml:

ports:
  - "8080:3456"

Option 3: Systemd Service

If you prefer systemd over pm2:

Create /etc/systemd/system/swarmclaw.service:

[Unit]
Description=SwarmClaw
After=network.target

[Service]
Type=simple
User=deploy
WorkingDirectory=/home/deploy/swarmclaw
ExecStart=/usr/bin/npm start
Restart=always
RestartSec=5
Environment=NODE_ENV=production
Environment=PORT=3456

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable swarmclaw
sudo systemctl start swarmclaw

Data Safety

These files are not tracked by git and are preserved across updates:

  • data/*.json — sessions, agents, tasks, credentials, etc.
  • data/*.db — SQLite databases (memory, activity)
  • .env.local — access key and encryption secret

Back up data/ and .env.local regularly. Without .env.local, encrypted credentials cannot be decrypted.

Security Checklist

  • Never expose port 3456 directly — always use a reverse proxy with TLS
  • Use the auto-generated access key (check .env.local)
  • Keep your VPS updated (sudo apt update && sudo apt upgrade)
  • Review agent system prompts before enabling shell or browser tools
  • Back up data/ and .env.local regularly