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:
- You need persistent storage
- 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
# 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.
adduser clawd
usermod -aG sudo clawd
Switch to the user:
su - clawd
4.4 Install Clawdbot
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:
sudo nano /etc/systemd/system/clawdbot.service
Paste the following unchanged:
[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:
sudo systemctl daemon-reload
sudo systemctl enable clawdbot
sudo systemctl start clawdbot
Check status:
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
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh
5.3 Docker Compose Setup
Create directories:
mkdir -p ~/clawdbot-docker/config ~/clawdbot-docker/workspace
docker-compose.yml:
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:
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:
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
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:
"telegram": {
"enable": true,
"token": "...",
"allowFrom": [123456789]
}
Without this, anyone who finds the bot can run commands.
9.2 Updates
LXC install:
npm install -g clawdbot@latest
systemctl restart clawdbot
Docker:
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.