Install Clawdbot on Ubuntu 22.04 VPS: Step-by-Step

You’re about to stand up a personal AI assistant on a small, affordable server. This beginner’s guide shows how to provision an Ubuntu 22.04 VPS, install Node.js 22, add a swap file for stability, and use the Clawdbot CLI to onboard and run a persistent gateway service. We’ll keep commands short and verification steps clear so you can copy, paste, and confirm each milestone.

What you’ll end up with: a Clawdbot gateway running as a systemd user service, connected to at least one LLM provider and one messaging channel, with basic firewall rules and simple update procedures.

Before you start

• An Ubuntu 22.04 VPS with 2GB RAM recommended and 40GB NVMe disk
• SSH access from your computer and a terminal
• One LLM API key and one messaging channel token (for example, a Telegram bot token)

Clawdbot’s official guidance requires modern Node.js. According to the gateway install pages, Node.js 22 or newer is the supported runtime for both the Gateway and CLI. See the installation overview in the Clawdbot docs under the page titled Install and the Linux platform notes for version specifics.

Provision your VPS on SurferCloud

Disclosure: SurferCloud is our product. Get Started: https://www.surfercloud.com/promos/ulighthost

Use a 2GB RAM plan so installs and updates complete reliably. You can browse current plans on the ULightHost page where the 1 vCPU, 2GB RAM, 40GB NVMe tier is shown.

• Order your server on the ULightHost promo page: see the plan grid and pick the 2GB RAM configuration shown on the page titled ULightHost.
• Image: Ubuntu 22.04 LTS.
• Networking: keep the default dedicated IPv4. Port 25 is blocked by default on promo plans.

If you need help with payment methods or account setup, reach out via the SurferCloud Contact page for assistance and billing guidance.

When the server is ready, note the public IP and the default Ubuntu username. On many cloud images, the user is ubuntu for Ubuntu 22.04. If your panel specifies a different username, use that.

Connect with SSH and prepare Ubuntu

From your local machine, connect to the VPS. Replace 203.0.113.10 with your server IP.

ssh ubuntu@203.0.113.10

Update system packages and install a few essentials. These tools help with builds, TLS, and diagnostics.

sudo apt update && sudo apt -y upgrade
sudo apt -y install git curl build-essential jq ca-certificates openssl ufw htop

Optional but helpful: set your timezone and verify free disk space.

sudo timedatectl set-timezone UTC
free -h && df -h

Install Node.js 22 on Ubuntu 22.04

Clawdbot requires Node.js 22 or newer. The NodeSource repository is a straightforward way to get current Node on Ubuntu 22.04. For background and supported commands, see the NodeSource distributions README.

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
node --version && npm --version

You should see a node version starting with v22 and a recent npm. If node prints an older version, repeat the steps and ensure there were no errors. If you prefer to validate requirements and onboarding flow, consult the Clawdbot documentation’s Install and Linux platform sections.

Add a small swap file on 2GB RAM

On a 2GB VPS, a modest swap file reduces the chance of out-of-memory kills during package installs or when Clawdbot loads dependencies. The standard Ubuntu swap-file procedure below is commonly used. For more background, consult Ubuntu’s community documentation on swap configuration.

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
sudo sysctl vm.swappiness=10

Verify that swap is active:

free -h
swapon --show

You should see Swap with approximately 2.0G total. If not, re-run the commands and check /etc/fstab for the swap entry.

Install Clawdbot on Ubuntu 22.04 VPS

Now you’ll install the Clawdbot CLI globally, run the onboarding wizard, and install a persistent service. The official Clawdbot install and wizard pages describe this flow, including what the onboarding wizard configures.

Install the CLI:

sudo npm install -g clawdbot@latest
clawdbot --version

Run the onboarding wizard and install the user-level systemd service for the gateway:

clawdbot onboard --install-daemon

The wizard will prompt you to:

• Authenticate or initialize a local profile
• Add at least one LLM provider key (for example, OpenAI or Anthropic)
• Add a messaging channel, such as a Telegram bot token (create one via BotFather; see the Telegram Bot API docs)

When onboarding completes, the gateway service is installed under your user account.

Keep the service running after logout

On Linux, user services stop when you log out unless lingering is enabled. Turn it on and check the service status.

sudo loginctl enable-linger "$USER"
systemctl --user daemon-reload
systemctl --user enable --now clawdbot-gateway.service
systemctl --user status clawdbot-gateway.service

You should see Active: active (running). If it’s not running, inspect logs:

journalctl --user -u clawdbot-gateway.service -f

Clawdbot also includes health and status commands. They provide quick diagnostics:

clawdbot status
clawdbot health
clawdbot gateway status
clawdbot gateway probe

Look for lines like Gateway reachable and a local probe URL such as ws://127.0.0.1:18789.

Secure the instance and expose only what you need

Keep the gateway bound to localhost unless you specifically need remote access or webhooks. For basic protection, configure UFW to allow SSH and otherwise deny inbound traffic.

sudo ufw allow OpenSSH
sudo ufw enable
sudo ufw status verbose

If you must expose a webhook or an admin endpoint on a domain, consider using NGINX as a reverse proxy with TLS via Certbot.

Example sketch with a domain of example.com:

sudo apt -y install nginx
sudo ufw allow 'Nginx Full'
# create a simple server block proxying to the local gateway port if needed
sudo nano /etc/nginx/sites-available/clawdbot.conf

Paste a minimal proxy and adjust the upstream port to match your gateway’s binding (keep it on 127.0.0.1):

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://127.0.0.1:18789;
        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_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Enable the site and obtain a certificate:

sudo ln -s /etc/nginx/sites-available/clawdbot.conf /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo snap install core; sudo snap refresh core
sudo snap install --classic certbot
sudo certbot --nginx -d example.com

If you don’t need public access, skip NGINX entirely and rely on local binding with UFW protecting the host.

Monitor, update, and back up

A few basics keep things smooth on a small VPS.

• Monitor resources briefly after first run:

htop
free -h
journalctl --user -u clawdbot-gateway.service -n 50

• Update Clawdbot to the latest release and restart the gateway:

sudo npm install -g clawdbot@latest
clawdbot gateway restart
clawdbot status && clawdbot health

• Back up config and consider snapshots before major updates. If you’ve set a custom state directory, back it up, or take a VPS snapshot from your provider’s panel.

Troubleshooting quick fixes

• Node version mismatch: If clawdbot errors on startup, verify node --version prints v22.x. Reinstall Node via the NodeSource steps and rerun npm install -g clawdbot@latest.
• Service not staying up: Ensure lingering is enabled with sudo loginctl enable-linger "$USER". Check systemctl --user status and journalctl logs for specific errors.
• Out-of-memory during installs: Add a 2–4GB swap file and retry. Close other processes; consider upgrading RAM if the workload grows.
• Port or firewall issues: Keep the gateway on 127.0.0.1 unless you know you need external access. If you must expose a port, allow it explicitly with UFW and confirm bindings with ss -ltnp.
• Channel or provider credentials: Re-run the onboarding to fix tokens, or use the CLI to inspect channels. Telegram tokens come from BotFather; double-check that your bot is added to the intended chat or group.

What’s next

You now have a working Clawdbot gateway on a small Ubuntu 22.04 VPS, with a stable Node.js 22 runtime, swap for resilience, and a persistent systemd user service. Add more channels, wire up additional providers, or script non-interactive onboarding for repeatable setups using the flags described in the Clawdbot documentation.

If you’d like help choosing a plan, payment options, or migrating to a larger instance, contact the team through the SurferCloud Contact page.

---

Selected references for deeper reading

• Clawdbot installation and getting started: consult the pages titled Install and Getting Started in the official Clawdbot docs — https://docs.clawd.bot/install and https://docs.clawd.bot/start/getting-started
• Clawdbot Linux platform and Gateway CLI: see https://docs.clawd.bot/platforms/linux and https://docs.clawd.bot/cli/gateway
• Node.js 22 on Ubuntu 22.04 via NodeSource: https://github.com/nodesource/distributions/blob/master/DEV_README.md
• Ubuntu firewall basics with UFW: https://documentation.ubuntu.com/server/how-to/security/firewalls/
• Certbot with NGINX on Ubuntu: https://certbot.eff.org/instructions
• Telegram Bot API and bot tokens: https://core.telegram.org/bots/api
• SurferCloud ULightHost promo page: https://www.surfercloud.com/promos/ulighthost
• SurferCloud Contact page: https://www.surfercloud.com/contact