Spaces:
Paused
Paused
| summary: "Run OpenClaw in a sandboxed macOS VM (local or hosted) when you need isolation or iMessage" | |
| read_when: | |
| - You want OpenClaw isolated from your main macOS environment | |
| - You want iMessage integration (BlueBubbles) in a sandbox | |
| - You want a resettable macOS environment you can clone | |
| - You want to compare local vs hosted macOS VM options | |
| title: "macOS VMs" | |
| # OpenClaw on macOS VMs (Sandboxing) | |
| ## Recommended default (most users) | |
| - **Small Linux VPS** for an always-on Gateway and low cost. See [VPS hosting](/vps). | |
| - **Dedicated hardware** (Mac mini or Linux box) if you want full control and a **residential IP** for browser automation. Many sites block data center IPs, so local browsing often works better. | |
| - **Hybrid:** keep the Gateway on a cheap VPS, and connect your Mac as a **node** when you need browser/UI automation. See [Nodes](/nodes) and [Gateway remote](/gateway/remote). | |
| Use a macOS VM when you specifically need macOS-only capabilities (iMessage/BlueBubbles) or want strict isolation from your daily Mac. | |
| ## macOS VM options | |
| ### Local VM on your Apple Silicon Mac (Lume) | |
| Run OpenClaw in a sandboxed macOS VM on your existing Apple Silicon Mac using [Lume](https://cua.ai/docs/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 | |
| ### Hosted Mac providers (cloud) | |
| If you want macOS in the cloud, hosted Mac providers work too: | |
| - [MacStadium](https://www.macstadium.com/) (hosted Macs) | |
| - Other hosted Mac vendors also work; follow their VM + SSH docs | |
| Once you have SSH access to a macOS VM, continue at step 6 below. | |
| --- | |
| ## Quick path (Lume, experienced users) | |
| 1. Install Lume | |
| 2. `lume create openclaw --os macos --ipsw latest` | |
| 3. Complete Setup Assistant, enable Remote Login (SSH) | |
| 4. `lume run openclaw --no-display` | |
| 5. SSH in, install OpenClaw, configure channels | |
| 6. Done | |
| --- | |
| ## What you need (Lume) | |
| - 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 | |
| ```bash | |
| /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: | |
| ```bash | |
| echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.zshrc && source ~/.zshrc | |
| ``` | |
| Verify: | |
| ```bash | |
| lume --version | |
| ``` | |
| Docs: [Lume Installation](https://cua.ai/docs/lume/guide/getting-started/installation) | |
| --- | |
| ## 2) Create the macOS VM | |
| ```bash | |
| lume create openclaw --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 | |
| ```bash | |
| lume get openclaw | |
| ``` | |
| Look for the IP address (usually `192.168.64.x`). | |
| --- | |
| ## 5) SSH into the VM | |
| ```bash | |
| ssh youruser@192.168.64.X | |
| ``` | |
| Replace `youruser` with the account you created, and the IP with your VM's IP. | |
| --- | |
| ## 6) Install OpenClaw | |
| Inside the VM: | |
| ```bash | |
| npm install -g openclaw@latest | |
| openclaw onboard --install-daemon | |
| ``` | |
| Follow the onboarding prompts to set up your model provider (Anthropic, OpenAI, etc.). | |
| --- | |
| ## 7) Configure channels | |
| Edit the config file: | |
| ```bash | |
| nano ~/.openclaw/openclaw.json | |
| ``` | |
| Add your channels: | |
| ```json | |
| { | |
| "channels": { | |
| "whatsapp": { | |
| "dmPolicy": "allowlist", | |
| "allowFrom": ["+15551234567"] | |
| }, | |
| "telegram": { | |
| "botToken": "YOUR_BOT_TOKEN" | |
| } | |
| } | |
| } | |
| ``` | |
| Then login to WhatsApp (scan QR): | |
| ```bash | |
| openclaw channels login | |
| ``` | |
| --- | |
| ## 8) Run the VM headlessly | |
| Stop the VM and restart without display: | |
| ```bash | |
| lume stop openclaw | |
| lume run openclaw --no-display | |
| ``` | |
| The VM runs in the background. OpenClaw's daemon keeps the gateway running. | |
| To check status: | |
| ```bash | |
| ssh youruser@192.168.64.X "openclaw status" | |
| ``` | |
| --- | |
| ## Bonus: iMessage integration | |
| This is the killer feature of running on macOS. Use [BlueBubbles](https://bluebubbles.app) to add iMessage to OpenClaw. | |
| Inside the VM: | |
| 1. Download BlueBubbles from bluebubbles.app | |
| 2. Sign in with your Apple ID | |
| 3. Enable the Web API and set a password | |
| 4. Point BlueBubbles webhooks at your gateway (example: `https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`) | |
| Add to your OpenClaw config: | |
| ```json | |
| { | |
| "channels": { | |
| "bluebubbles": { | |
| "serverUrl": "http://localhost:1234", | |
| "password": "your-api-password", | |
| "webhookPath": "/bluebubbles-webhook" | |
| } | |
| } | |
| } | |
| ``` | |
| Restart the gateway. Now your agent can send and receive iMessages. | |
| Full setup details: [BlueBubbles channel](/channels/bluebubbles) | |
| --- | |
| ## Save a golden image | |
| Before customizing further, snapshot your clean state: | |
| ```bash | |
| lume stop openclaw | |
| lume clone openclaw openclaw-golden | |
| ``` | |
| Reset anytime: | |
| ```bash | |
| lume stop openclaw && lume delete openclaw | |
| lume clone openclaw-golden openclaw | |
| lume run openclaw --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 a small VPS. See [VPS hosting](/vps). | |
| --- | |
| ## 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 openclaw` 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 `openclaw channels login` | | |
| --- | |
| ## Related docs | |
| - [VPS hosting](/vps) | |
| - [Nodes](/nodes) | |
| - [Gateway remote](/gateway/remote) | |
| - [BlueBubbles channel](/channels/bluebubbles) | |
| - [Lume Quickstart](https://cua.ai/docs/lume/guide/getting-started/quickstart) | |
| - [Lume CLI Reference](https://cua.ai/docs/lume/reference/cli-reference) | |
| - [Unattended VM Setup](https://cua.ai/docs/lume/guide/fundamentals/unattended-setup) (advanced) | |
| - [Docker Sandboxing](/install/docker) (alternative isolation approach) | |