Running Clawdbot on Proxmox: A Practical Guide for Real Humans

This guide explains how to run **Clawdbot**, a self-hosted AI agent, on **Proxmox Virtual Environment (VE)** in a way that is stable, secure, and maintainable. Clawdbot is not a "run it once and forget it" tool. It's a long-running process that holds state, executes commands, stores memory, and stays connected to messaging platforms. That means it behaves much more like a server application than a chatbot. Because of that, laptops are a poor long-term home. Servers are better. And for many homelabs, Proxmox is where servers live. This document walks through the architectural realities, the sharp edges you'll hit, and the exact steps needed to make Clawdbot behave nicely inside Proxmox. --- ## 1. From Chatbots to Agents (Why This Is Different) ### 1.1 Chatbots End Conversations. Agents Don't. Traditional chatbots respond to text and then disappear. Agents stick around. Clawdbot runs as a Node.js application that gives an LLM access to tools and a real runtime environment. That means it can: - Execute shell commands - Read and write files - Maintain memory across sessions - Stay connected to Telegram or WhatsApp - Run continuously in the background Once you treat an AI like this, you also have to treat its infrastructure seriously. ### 1.2 The "Local-First" Philosophy Clawdbot follows a local-first model. Configuration, memory, and state live on disk under the user's home directory, not on someone else's servers. This has two practical implications: 1. You need persistent storage 2. You need backups Proxmox already solves both problems well, which makes it a good fit. The catch is that Clawdbot was originally designed for desktop environments. Proxmox is not a desktop environment. That mismatch is where most problems come from. --- ## 2. Understanding the Proxmox Environment Before installing anything, it helps to understand the hosting options Proxmox gives you. ### 2.1 Virtual Machines VMs behave exactly like normal Linux systems. **Pros:** - systemd behaves normally - user sessions work - Clawdbot's default install path works **Cons:** - Higher memory and CPU overhead - Overkill for a lightweight Node.js service If you want the easiest path, use a VM. ### 2.2 Linux Containers (LXC) LXCs are lighter and faster. They share the host kernel and are ideal for always-on services. **Pros:** - Very low overhead - Fast startup - Easy snapshots **The problem:** - No real user session - No working `systemd --user` - No user D-Bus Clawdbot expects all three. That's why a normal `clawdbot onboard --install-daemon` fails in an unprivileged LXC. This guide focuses on fixing that. --- ## 3. What You Need Before Installing ### 3.1 Hardware **Cloud-based inference:** - 2 vCPU - 2–4 GB RAM **Local models:** - 16 GB+ RAM - GPU passthrough if possible **Storage:** - Minimum 20 GB - More if you plan to store lots of files or logs ### 3.2 Operating System Debian 12 (Bookworm) is recommended. Ubuntu 22.04 or 24.04 also works. Examples below assume Debian 12. ### 3.3 Node.js Version Matters Clawdbot **requires Node.js 22+**. The default Debian repositories usually ship older versions. Installing `nodejs` directly from apt will not work. You must use NodeSource. --- ## 4. Deployment Strategy A: LXC With a System-Level Service This approach installs Clawdbot directly inside an LXC and runs it as a system service. It's efficient and stable once configured. ### 4.1 Create the Container - Debian 12 template - Unprivileged container enabled - Static IP recommended Start the container and open a shell. --- ### 4.2 Install Dependencies and Node.js ```bash # Update base system apt update && apt upgrade -y # Install prerequisites apt install -y curl git build-essential sudo python3 # Add NodeSource repository for Node.js 22 curl -fsSL https://deb.nodesource.com/setup_22.x -o nodesource_setup.sh bash nodesource_setup.sh # Install Node.js apt install -y nodejs # Verify version node -v ``` Make sure this prints `v22.x.x`. --- ### 4.3 Create a Dedicated User Running this as root is unnecessary and risky. ```bash adduser clawd usermod -aG sudo clawd ``` Switch to the user: ```bash su - clawd ``` --- ### 4.4 Install Clawdbot ```bash npm install -g clawdbot@latest ``` At this point, **do not** run the daemon installer. It will fail. --- ### 4.5 Why `systemd --user` Fails Here Clawdbot normally installs itself as a user service. In an unprivileged LXC: - The user systemd instance isn't running - The user D-Bus socket doesn't exist The result is an error like: > Failed to connect to user scope bus This is expected. The fix is to run Clawdbot as a **system service** that executes as the `clawd` user. --- ### 4.6 Create a Systemd Service As root: ```bash sudo nano /etc/systemd/system/clawdbot.service ``` Paste the following **unchanged**: ```ini [Unit] Description=Clawdbot Gateway Service Documentation=https://github.com/clawdbot/clawdbot After=network.target [Service] User=clawd Group=clawd Environment=HOME=/home/clawd Environment=NODE_ENV=production Environment=CLAWDBOT_GATEWAY_BIND=0.0.0.0 Environment=CLAWDBOT_GATEWAY_PORT=18789 ExecStart=/usr/bin/node /usr/lib/node_modules/clawdbot/dist/index.js gateway Restart=always RestartSec=10 StandardOutput=journal StandardError=journal [Install] WantedBy=multi-user.target ``` Enable and start: ```bash sudo systemctl daemon-reload sudo systemctl enable clawdbot sudo systemctl start clawdbot ``` Check status: ```bash sudo systemctl status clawdbot ``` --- ### 4.7 About `clawdbot doctor` `clawdbot doctor` will complain about the daemon. Ignore that part. It only knows how to check user services. Your service is working if `systemctl status` says it is. --- ## 5. Deployment Strategy B: Docker (Optional) If you prefer containerized builds and immutable environments, Docker is a valid alternative. ### 5.1 Enable Nesting in Proxmox For the LXC: - Enable **nesting** - Enable **keyctl** --- ### 5.2 Install Docker ```bash curl -fsSL https://get.docker.com -o get-docker.sh sh get-docker.sh ``` --- ### 5.3 Docker Compose Setup Create directories: ```bash mkdir -p ~/clawdbot-docker/config ~/clawdbot-docker/workspace ``` `docker-compose.yml`: ```yaml services: clawdbot: image: ghcr.io/gsaraiva2109/clawdbot-build:latest container_name: clawdbot restart: unless-stopped network_mode: host environment: - HOME=/home/node - TERM=xterm-256color - CLAWDBOT_GATEWAY_BIND=0.0.0.0 - CLAWDBOT_GATEWAY_PORT=18789 - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY} volumes: - ./config:/home/node/.clawdbot - ./workspace:/home/node/clawd ``` Host networking is recommended for mDNS discovery. --- ## 6. Networking and Gateway Access ### 6.1 Binding By default, Clawdbot binds to localhost. For headless setups, you must override this: ```bash CLAWDBOT_GATEWAY_BIND=0.0.0.0 ``` --- ### 6.2 Secure Onboarding With SSH Tunnel Do not expose the gateway publicly during setup. From your workstation: ```bash ssh -L 18789:127.0.0.1:18789 user@<lxc_ip> ``` Then open: ``` http://127.0.0.1:18789 ``` --- ## 7. Onboarding and Configuration The wizard lets you: - Name the agent - Select the LLM provider - Add API keys - Pair Telegram or WhatsApp All configuration is stored in: ``` ~/.clawdbot/ ``` This directory is the entire "brain" of the agent. Back it up. --- ## 8. Operating the Agent ### 8.1 Logs ```bash journalctl -u clawdbot -f ``` This shows: - Model calls - Tool execution - Gateway activity --- ### 8.2 Messaging as a Terminal Once connected, messaging platforms effectively become a remote shell. This is powerful. It is also dangerous if access is not restricted. --- ## 9. Security Basics (Do Not Skip) ### 9.1 Restrict Who Can Talk to the Bot Use `allowFrom` in `clawdbot.json`: ```json "telegram": { "enable": true, "token": "...", "allowFrom": [123456789] } ``` Without this, anyone who finds the bot can run commands. --- ### 9.2 Updates **LXC install:** ```bash npm install -g clawdbot@latest systemctl restart clawdbot ``` **Docker:** ```bash docker compose pull docker compose up -d ``` --- ## 10. Final Notes Running Clawdbot on Proxmox turns your server from a passive box into an active participant. It can observe, reason, and act. The biggest hurdle is not performance. It's understanding where desktop assumptions break in server environments. Once you address that, Clawdbot runs cleanly, predictably, and safely inside Proxmox. --- ## Related Resources - [Proxmox VE Documentation](https://pve.proxmox.com/wiki/Main_Page) - [Clawdbot GitHub Repository](https://github.com/clawdbot/clawdbot) - [NodeSource Node.js Binary Distributions](https://github.com/nodesource/distributions) - [r/Proxmox Community](https://www.reddit.com/r/Proxmox/)