ClawdBot for Linux

🐧 Supported Linux Distributions

System Requirements

🟠 Ubuntu/Debian Installation

Best for: Beginners, servers, most users

Quick Install (One-Command)

# Complete installation script
curl -fsSL https://raw.githubusercontent.com/steipete/ClawdBot/main/scripts/install-ubuntu.sh | bash

Manual Installation

Step 1: Update System

sudo apt update && sudo apt upgrade -y

Step 2: Install Node.js 22

# Add NodeSource repository
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

# Install Node.js
sudo apt-get install -y nodejs

# Verify installation
node --version  # Should show v22.x.x
npm --version   # Should show 10.x.x+

Step 3: Install Build Tools (Optional but Recommended)

sudo apt-get install -y build-essential git curl

Step 4: Install ClawdBot

# Install globally
sudo npm install -g clawdbot@latest

# Or install for current user only (no sudo)
npm install -g clawdbot@latest

# Verify installation
clawdbot --version

Step 5: Run Onboarding

clawdbot onboard

Ubuntu-Specific Optimizations

# Increase file descriptor limit
echo "* soft nofile 65536" | sudo tee -a /etc/security/limits.conf
echo "* hard nofile 65536" | sudo tee -a /etc/security/limits.conf

# Enable automatic security updates
sudo apt install unattended-upgrades
sudo dpkg-reconfigure -plow unattended-upgrades

🔵 Arch Linux Installation

Best for: Advanced users, latest packages

Using pacman

# Update system
sudo pacman -Syu

# Install Node.js
sudo pacman -S nodejs npm

# Install ClawdBot
npm install -g clawdbot@latest

Using AUR (yay)

# Install from AUR (if available)
yay -S clawdbot

# Or use npm method above

Arch-Specific Tips

# Install base-devel for compilation
sudo pacman -S base-devel

# Keep system updated
sudo pacman -Syu --noconfirm

🔴 Fedora/RHEL Installation

Best for: Enterprise, Red Hat ecosystem

Fedora Installation

# Update system
sudo dnf update -y

# Install Node.js
sudo dnf install -y nodejs npm

# Verify version (should be 18+, upgrade if needed)
node --version

# If Node.js is too old, use NodeSource:
curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -
sudo dnf install -y nodejs

# Install ClawdBot
sudo npm install -g clawdbot@latest

RHEL/CentOS Installation

# Enable EPEL repository
sudo dnf install -y epel-release

# Install Node.js from NodeSource
curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -
sudo dnf install -y nodejs

# Install ClawdBot
sudo npm install -g clawdbot@latest

SELinux Configuration

# If SELinux is enabled, you may need to adjust policies
sudo setenforce 0  # Temporary, for testing

# For permanent (not recommended for production):
# Edit /etc/selinux/config and set SELINUX=permissive

# Better: Create custom SELinux policy for ClawdBot
# (Advanced - consult SELinux documentation)

⚙️ Systemd Service Setup

Run ClawdBot as a system service for 24/7 operation.

Automatic Setup

# ClawdBot includes a service installer
clawdbot service install

# Start service
sudo systemctl start clawdbot

# Enable auto-start on boot
sudo systemctl enable clawdbot

# Check status
sudo systemctl status clawdbot

Manual Service Configuration

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

[Unit]
Description=ClawdBot AI Assistant
After=network.target

[Service]
Type=simple
User=clawdbot
WorkingDirectory=/home/clawdbot
ExecStart=/usr/bin/clawdbot start
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

# Environment variables
Environment="NODE_ENV=production"
Environment="CONFIG_PATH=/home/clawdbot/.clawdbot/config.yaml"

# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=read-only
ReadWritePaths=/home/clawdbot/.clawdbot

[Install]
WantedBy=multi-user.target

Service Management Commands

# Reload systemd after editing service file
sudo systemctl daemon-reload

# Start service
sudo systemctl start clawdbot

# Stop service
sudo systemctl stop clawdbot

# Restart service
sudo systemctl restart clawdbot

# View logs
sudo journalctl -u clawdbot -f

# View last 100 lines
sudo journalctl -u clawdbot -n 100

Create Dedicated User (Recommended)

# Create system user for ClawdBot
sudo useradd -r -s /bin/bash -d /home/clawdbot -m clawdbot

# Switch to clawdbot user
sudo su - clawdbot

# Install ClawdBot as this user
npm install -g clawdbot@latest

# Configure
clawdbot onboard

⚡ Linux Optimization

Performance Tuning

1. Increase File Descriptors

# Edit /etc/security/limits.conf
* soft nofile 65536
* hard nofile 65536

# Or for specific user
clawdbot soft nofile 65536
clawdbot hard nofile 65536

# Apply immediately
ulimit -n 65536

2. Optimize Network Settings

# Edit /etc/sysctl.conf
net.core.somaxconn = 1024
net.ipv4.tcp_max_syn_backlog = 2048
net.ipv4.ip_local_port_range = 1024 65535

# Apply changes
sudo sysctl -p

3. Enable Swap (for systems with limited RAM)

# Create 4GB swap file
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Make permanent
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

4. Use Process Manager (PM2)

# Install PM2
npm install -g pm2

# Start ClawdBot with PM2
pm2 start clawdbot --name "clawdbot-gateway"

# Save PM2 configuration
pm2 save

# Setup PM2 to start on boot
pm2 startup

# Monitor
pm2 monit

Security Hardening

1. Configure Firewall

# UFW (Ubuntu/Debian)
sudo ufw allow 22/tcp    # SSH
sudo ufw allow 3000/tcp  # ClawdBot (if needed)
sudo ufw enable

# firewalld (Fedora/RHEL)
sudo firewall-cmd --permanent --add-port=3000/tcp
sudo firewall-cmd --reload

2. Setup Fail2Ban

# Install fail2ban
sudo apt install fail2ban  # Ubuntu/Debian
sudo dnf install fail2ban  # Fedora

# Enable and start
sudo systemctl enable fail2ban
sudo systemctl start fail2ban

3. Regular Updates

# Create update script
cat > ~/update-clawdbot.sh << 'EOF'
#!/bin/bash
npm update -g clawdbot
sudo systemctl restart clawdbot
EOF

chmod +x ~/update-clawdbot.sh

# Add to crontab (weekly updates)
(crontab -l 2>/dev/null; echo "0 3 * * 0 ~/update-clawdbot.sh") | crontab -

🔧 Troubleshooting

Common Issues

Issue: "npm: command not found"

Solution:

# Node.js not installed or not in PATH
# Reinstall Node.js (see distribution-specific instructions above)

# Check PATH
echo $PATH

# Add npm to PATH (if needed)
export PATH="$PATH:/usr/local/bin"

Issue: Permission Denied

Solution:

# Fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Reinstall ClawdBot
npm install -g clawdbot@latest

Issue: Port 3000 Already in Use

Solution:

# Find process using port
sudo lsof -i :3000

# Kill process
sudo kill -9 [PID]

# Or change ClawdBot port in config
# Edit ~/.clawdbot/config.yaml
server:
  port: 3001

Issue: Systemd Service Won't Start

Solution:

# Check service status
sudo systemctl status clawdbot

# View detailed logs
sudo journalctl -u clawdbot -n 50 --no-pager

# Check file permissions
ls -la /home/clawdbot/.clawdbot/

# Verify user exists
id clawdbot

Issue: Out of Memory

Solution:

# Check memory usage
free -h

# Add swap space (see optimization section)

# Limit Node.js memory
# Edit systemd service file
Environment="NODE_OPTIONS=--max-old-space-size=2048"

❓ Linux FAQ