OpenClaw VM

A sandboxed Vagrant virtual machine for safely running and testing OpenClaw - the open-source autonomous AI agent (formerly Moltbot / Clawdbot).

Why a VM?

OpenClaw is a powerful AI agent with full system access -- shell, files, browser, messaging platforms. Running it directly on your personal machine raises security concerns. This project provides a pre-configured, isolated VM so you can:

• Test safely -- OpenClaw runs inside a disposable VM, not on your host
• Experiment freely -- try agent capabilities without risk to your data
• Tear down and rebuild -- vagrant destroy && vagrant up for a clean slate
• Access from host -- Gateway dashboard forwarded to localhost:18789 (token required)
• Auto-start -- Gateway daemon starts automatically on login after setup

What's Included

Category	Software
OS	Ubuntu 22.04 LTS with XFCE desktop
AI Agent	OpenClaw (latest), Node.js 22, pnpm
Browser	Google Chrome
Office	LibreOffice
Media	VLC
Dev Tools	Git, vim, nano, htop, curl, wget
Package Mgr	snapd, apt
Extras	Evince (PDF), Ristretto (images), p7zip, system monitor

Prerequisites

• VirtualBox (7.0 or later)
• Vagrant (2.4 or later)

Windows

1. Download and install VirtualBox from https://www.virtualbox.org/wiki/Downloads
2. Download and install Vagrant from https://www.vagrantup.com/downloads
3. Reboot your system after installation

macOS

brew install --cask virtualbox
brew install --cask vagrant

Linux

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install virtualbox vagrant

# Fedora
sudo dnf install virtualbox vagrant

# Arch Linux
sudo pacman -S virtualbox vagrant

Quick Start

# Clone this repository
git clone https://github.com/YOUR_USERNAME/openclaw-vm.git
cd openclaw-vm

# Start the VM (first run downloads the base box and provisions)
vagrant up

# The XFCE desktop GUI opens automatically
# Login: vagrant / vagrant

Setting Up OpenClaw

After the desktop loads:

1. Run the onboarding wizard -- double-click "OpenClaw Setup" on the desktop, or open a terminal and run:

   openclaw onboard --install-daemon

   This walks you through:

   • Choosing an AI provider (Anthropic, OpenAI, etc.) and entering API keys
   • Configuring messaging channels (Telegram, Discord, WhatsApp, etc.)
   • Installing the gateway daemon as a user systemd service

2. Get your gateway token -- the dashboard requires a token for authentication. Find it with:

   cat ~/.openclaw/openclaw.json | grep -A 2 '"auth"'

   Look for the "token" value (a long hex string).

3. Access the dashboard -- open Chrome and visit:

   http://127.0.0.1:18789/?token=YOUR_TOKEN_HERE
   

   Replace YOUR_TOKEN_HERE with the token from step 2.

   The dashboard is also accessible from your host machine at:

   http://localhost:18789/?token=YOUR_TOKEN_HERE
   

4. Use the TUI -- double-click "OpenClaw TUI" or run openclaw in a terminal.

Gateway Auto-Start

After onboarding, the gateway daemon auto-starts on every login via a systemd user service. Check status with:

systemctl --user status openclaw-gateway

Manual controls:

systemctl --user start openclaw-gateway    # Start
systemctl --user stop openclaw-gateway     # Stop
systemctl --user restart openclaw-gateway  # Restart

VM Management

vagrant up        # Start the VM
vagrant halt      # Shut down the VM
vagrant reload    # Restart the VM
vagrant ssh       # SSH into the VM (headless)
vagrant destroy   # Delete the VM entirely
vagrant provision # Re-run provisioning on existing VM

Configuration

Default VM specs (edit Vagrantfile to adjust):

Setting	Default
RAM	4 GB
CPUs	2 cores
Video RAM	128 MB
3D Acceleration	Enabled
Clipboard	Bidirectional
Drag and Drop	Bidirectional
Nested Virtualization	Enabled

Troubleshooting

See docs/troubleshooting.md for detailed solutions. Quick fixes:

GUI window doesn't appear

Ensure vb.gui = true is set in the Vagrantfile. Check that VirtualBox Extension Pack is installed.

Dashboard shows "unauthorized: gateway token missing"

The dashboard requires a token for authentication. Find your token:

vagrant ssh
cat ~/.openclaw/openclaw.json | grep '"token"'

Then access the dashboard with the token in the URL:

http://localhost:18789/?token=YOUR_TOKEN_HERE

OpenClaw TUI icon opens and closes immediately

The desktop launcher has been updated to keep the terminal open. If you're on an older VM build, manually fix it:

cat > ~/Desktop/openclaw-tui.desktop <<'EOF'
[Desktop Entry]
Version=1.0
Type=Application
Name=OpenClaw TUI
Comment=Launch OpenClaw Terminal Interface
Exec=xfce4-terminal -e "bash -c 'openclaw || bash'"
Icon=utilities-terminal
Terminal=false
Categories=Development;
EOF

chmod +x ~/Desktop/openclaw-tui.desktop

OpenClaw command not found

SSH into the VM and reinstall:

vagrant ssh
sudo npm install -g openclaw@latest

Port 18789 already in use on host

Vagrant auto-corrects port conflicts. Check vagrant port to see the actual mapping, or stop whatever is using port 18789 on your host.

Gateway not running after reboot

The gateway runs as a user service and starts on login. Check status:

vagrant ssh
systemctl --user status openclaw-gateway

If it's not running, you may need to complete the onboarding first (openclaw onboard --install-daemon).

VM is slow

Increase resources in the Vagrantfile:

vb.memory = "8192"  # 8GB RAM
vb.cpus = 4         # 4 CPU cores

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines.

License

MIT License -- see LICENSE for details.

Links

• OpenClaw -- Main OpenClaw repository
• OpenClaw Docs -- Official documentation
• openclaw.ai -- Project website
• Vagrant -- VM automation
• VirtualBox -- Virtualization platform