clawdbot/docs/platforms/macos-vm.md

summary, read_when

summary	read_when
Run Clawdbot in a sandboxed macOS VM on your existing Apple Silicon Mac using Lume	You want Clawdbot isolated from your main macOS environment You want iMessage integration (BlueBubbles) in a sandbox You already have an Apple Silicon Mac and don't want to buy extra hardware You want to reset your Clawdbot environment easily by cloning VMs

Clawdbot on Lume (macOS Sandbox)

Goal

Run Clawdbot in a sandboxed macOS VM on your existing Apple Silicon Mac using Lume.

This gives you:

• Full macOS environment in isolation (your host stays clean)
• iMessage support via BlueBubbles (impossible on Linux/Windows)
• Instant reset by cloning VMs
• No extra hardware or cloud costs

What are we doing?

• Install Lume on your Mac (VM manager using Apple's Virtualization Framework)
• Create a macOS VM
• SSH into the VM
• Install and configure Clawdbot inside the VM
• Run the VM headlessly in the background

The Gateway runs inside the VM. You access it via SSH or the VM's IP.

---

Quick path (experienced users)

1. Install Lume
2. lume create clawdbot --os macos --ipsw latest
3. Complete Setup Assistant, enable Remote Login (SSH)
4. lume run clawdbot --no-display
5. SSH in, install Clawdbot, configure channels
6. Done

---

What you need

• Apple Silicon Mac (M1/M2/M3/M4)
• macOS Sequoia or later on the host
• ~60 GB free disk space per VM
• ~20 minutes

---

1) Install Lume

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"

If ~/.local/bin isn't in your PATH:

echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.zshrc && source ~/.zshrc

Verify:

lume --version

Docs: Lume Installation

---

2) Create the macOS VM

lume create clawdbot --os macos --ipsw latest

This downloads macOS and creates the VM. A VNC window opens automatically.

Note: The download can take a while depending on your connection.

---

3) Complete Setup Assistant

In the VNC window:

1. Select language and region
2. Skip Apple ID (or sign in if you want iMessage later)
3. Create a user account (remember the username and password)
4. Skip all optional features

After setup completes, enable SSH:

1. Open System Settings → General → Sharing
2. Enable "Remote Login"

---

4) Get the VM's IP address

lume get clawdbot

Look for the IP address (usually 192.168.64.x).

---

5) SSH into the VM

ssh youruser@192.168.64.X

Replace youruser with the account you created, and the IP with your VM's IP.

---

6) Install Clawdbot

Inside the VM:

npm install -g clawdbot@latest
clawdbot onboard --install-daemon

Follow the onboarding prompts to set up your model provider (Anthropic, OpenAI, etc.).

---

7) Configure channels

Edit the config file:

nano ~/.clawdbot/clawdbot.json

Add your channels:

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+15551234567"]
    },
    "telegram": {
      "botToken": "YOUR_BOT_TOKEN"
    }
  }
}

Then login to WhatsApp (scan QR):

clawdbot channels login

---

8) Run the VM headlessly

Stop the VM and restart without display:

lume stop clawdbot
lume run clawdbot --no-display

The VM runs in the background. Clawdbot's daemon keeps the gateway running.

To check status:

ssh youruser@192.168.64.X "clawdbot status"

---

Bonus: iMessage integration

This is the killer feature of running on macOS. Use BlueBubbles to add iMessage to Clawdbot.

Inside the VM:

1. Download BlueBubbles from bluebubbles.app
2. Sign in with your Apple ID
3. Enable the Web API in BlueBubbles settings

Add to your Clawdbot config:

{
  "channels": {
    "bluebubbles": {
      "serverUrl": "http://localhost:1234",
      "password": "your-api-password"
    }
  }
}

Restart the gateway. Now your agent can send and receive iMessages.

---

Save a golden image

Before customizing further, snapshot your clean state:

lume stop clawdbot
lume clone clawdbot clawdbot-golden

Reset anytime:

lume stop clawdbot && lume delete clawdbot
lume clone clawdbot-golden clawdbot
lume run clawdbot --no-display

---

Running 24/7

Keep the VM running by:

• Keeping your Mac plugged in
• Disabling sleep in System Settings → Energy Saver
• Using caffeinate if needed

For true always-on, consider a dedicated Mac Mini or cloud Mac instances.

---

Troubleshooting

Problem	Solution
Can't SSH into VM	Check "Remote Login" is enabled in VM's System Settings
VM IP not showing	Wait for VM to fully boot, run lume get clawdbot again
Lume command not found	Add ~/.local/bin to your PATH
WhatsApp QR not scanning	Ensure you're logged into the VM (not host) when running clawdbot channels login

---

Related docs

• Lume Quickstart
• Lume CLI Reference
• Unattended VM Setup (advanced)
• Docker Sandboxing (alternative isolation approach)