docs: expand macOS VM guide (#1693) (thanks @f-trycua)

Add documentation for running Clawdbot in a sandboxed macOS VM
using Lume. This provides an alternative to buying dedicated
hardware or using cloud instances.

The guide covers:
- Installing Lume on Apple Silicon Macs
- Creating and configuring a macOS VM
- Installing Clawdbot inside the VM
- Running headlessly for 24/7 operation
- iMessage integration via BlueBubbles
- Saving golden images for easy reset

CHANGELOG.md

@@ -14,6 +14,7 @@ Docs: https://docs.clawd.bot
 - TTS: add auto mode enum (off/always/inbound/tagged) with per-session `/tts` override. (#1667) Thanks @sebslight. https://docs.clawd.bot/tts
 - Docs: expand FAQ (migration, scheduling, concurrency, model recommendations, OpenAI subscription auth, Pi sizing, hackable install, docs SSL workaround).
 - Docs: add verbose installer troubleshooting guidance.
+- Docs: add macOS VM guide with local/hosted options + VPS/nodes guidance. (#1693) Thanks @f-trycua.
 - Docs: update Fly.io guide notes.
 - Docs: add Bedrock EC2 instance role setup + IAM steps. (#1625) Thanks @sergical. https://docs.clawd.bot/bedrock
 - Exec approvals: forward approval prompts to chat with `/approve` for all channels (including plugins). (#1621) Thanks @czekaj. https://docs.clawd.bot/tools/exec-approvals https://docs.clawd.bot/tools/slash-commands
@@ -30,12 +31,14 @@ Docs: https://docs.clawd.bot
 - Telegram: use wrapped fetch for long-polling on Node to normalize AbortSignal handling. (#1639)
 - Telegram: set fetch duplex="half" for uploads on Node 22 to avoid sendPhoto failures. (#1684) Thanks @commdata2338.
 - Signal: repair reaction sends (group/UUID targets + CLI author flags). (#1651) Thanks @vilkasdev.
+- Signal: add configurable signal-cli startup timeout + external daemon mode docs. (#1677) https://docs.clawd.bot/channels/signal
 - Exec: keep approvals for elevated ask unless full mode. (#1616) Thanks @ivancasco.
 - Agents: auto-compact on context overflow prompt errors before failing. (#1627) Thanks @rodrigouroz.
 - Agents: use the active auth profile for auto-compaction recovery.
 - Models: default missing custom provider fields so minimal configs are accepted.
 - Gateway: skip Tailscale DNS probing when tailscale.mode is off. (#1671)
 - Gateway: reduce log noise for late invokes + remote node probes; debounce skills refresh. (#1607) Thanks @petter-b.
+- Gateway: clarify Control UI/WebChat auth error hints for missing tokens. (#1690)
 - macOS: default direct-transport `ws://` URLs to port 18789; document `gateway.remote.transport`. (#1603) Thanks @ngutman.
 - Voice Call: return stream TwiML for outbound conversation calls on initial Twilio webhook. (#1634)
 - Google Chat: tighten email allowlist matching, typing cleanup, media caps, and onboarding/docs/tests. (#1635) Thanks @iHildy.

docs/channels/signal.md

@@ -74,6 +74,22 @@ Example:
 
 Multi-account support: use `channels.signal.accounts` with per-account config and optional `name`. See [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) for the shared pattern.
 
+## External daemon mode (httpUrl)
+If you want to manage `signal-cli` yourself (slow JVM cold starts, container init, or shared CPUs), run the daemon separately and point Clawdbot at it:
+
+```json5
+{
+  channels: {
+    signal: {
+      httpUrl: "http://127.0.0.1:8080",
+      autoStart: false
+    }
+  }
+}
+```
+
+This skips auto-spawn and the startup wait inside Clawdbot. For slow starts when auto-spawning, set `channels.signal.startupTimeoutMs`.
+
 ## Access control (DMs + groups)
 DMs:
 - Default: `channels.signal.dmPolicy = "pairing"`.
@@ -142,6 +158,7 @@ Provider options:
 - `channels.signal.httpUrl`: full daemon URL (overrides host/port).
 - `channels.signal.httpHost`, `channels.signal.httpPort`: daemon bind (default 127.0.0.1:8080).
 - `channels.signal.autoStart`: auto-spawn daemon (default true if `httpUrl` unset).
+- `channels.signal.startupTimeoutMs`: startup wait timeout in ms (cap 120000).
 - `channels.signal.receiveMode`: `on-start | manual`.
 - `channels.signal.ignoreAttachments`: skip attachment downloads.
 - `channels.signal.ignoreStories`: ignore stories from the daemon.

docs/docs.json

@@ -1048,6 +1048,7 @@
         "pages": [
           "platforms",
           "platforms/macos",
+          "platforms/macos-vm",
           "platforms/ios",
           "platforms/android",
           "platforms/windows",

docs/platforms/macos-vm.md

@@ -0,0 +1,275 @@
+---
+summary: "Run Clawdbot in a sandboxed macOS VM (local or hosted) when you need isolation or iMessage"
+read_when:
+  - You want Clawdbot 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
+---
+
+# Clawdbot 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 Clawdbot 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 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 (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 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
+
+```bash
+lume get clawdbot
+```
+
+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 Clawdbot
+
+Inside the VM:
+
+```bash
+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:
+
+```bash
+nano ~/.clawdbot/clawdbot.json
+```
+
+Add your channels:
+
+```json
+{
+  "channels": {
+    "whatsapp": {
+      "dmPolicy": "allowlist",
+      "allowFrom": ["+15551234567"]
+    },
+    "telegram": {
+      "botToken": "YOUR_BOT_TOKEN"
+    }
+  }
+}
+```
+
+Then login to WhatsApp (scan QR):
+
+```bash
+clawdbot channels login
+```
+
+---
+
+## 8) Run the VM headlessly
+
+Stop the VM and restart without display:
+
+```bash
+lume stop clawdbot
+lume run clawdbot --no-display
+```
+
+The VM runs in the background. Clawdbot's daemon keeps the gateway running.
+
+To check status:
+
+```bash
+ssh youruser@192.168.64.X "clawdbot status"
+```
+
+---
+
+## Bonus: iMessage integration
+
+This is the killer feature of running on macOS. Use [BlueBubbles](https://bluebubbles.app) 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 and set a password
+4. Point BlueBubbles webhooks at your gateway (example: `https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`)
+
+Add to your Clawdbot 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 clawdbot
+lume clone clawdbot clawdbot-golden
+```
+
+Reset anytime:
+
+```bash
+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 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 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
+
+- [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)

src/config/types.signal.ts

@@ -33,6 +33,8 @@ export type SignalAccountConfig = {
   cliPath?: string;
   /** Auto-start signal-cli daemon (default: true if httpUrl not set). */
   autoStart?: boolean;
+  /** Max time to wait for signal-cli daemon startup (ms, cap 120000). */
+  startupTimeoutMs?: number;
   receiveMode?: "on-start" | "manual";
   ignoreAttachments?: boolean;
   ignoreStories?: boolean;

src/config/zod-schema.providers-core.ts

@@ -486,6 +486,7 @@ export const SignalAccountSchemaBase = z
     httpPort: z.number().int().positive().optional(),
     cliPath: ExecutableTokenSchema.optional(),
     autoStart: z.boolean().optional(),
+    startupTimeoutMs: z.number().int().min(1000).max(120000).optional(),
     receiveMode: z.union([z.literal("on-start"), z.literal("manual")]).optional(),
     ignoreAttachments: z.boolean().optional(),
     ignoreStories: z.boolean().optional(),

src/gateway/server.auth.e2e.test.ts

@@ -230,6 +230,21 @@ describe("gateway server auth/connect", () => {
       ws.close();
     });
 
+    test("returns control ui hint when token is missing", async () => {
+      const ws = await openWs(port);
+      const res = await connectReq(ws, {
+        client: {
+          id: GATEWAY_CLIENT_NAMES.CONTROL_UI,
+          version: "1.0.0",
+          platform: "web",
+          mode: GATEWAY_CLIENT_MODES.WEBCHAT,
+        },
+      });
+      expect(res.ok).toBe(false);
+      expect(res.error?.message ?? "").toContain("Control UI settings");
+      ws.close();
+    });
+
     test("rejects control ui without device identity by default", async () => {
       const ws = await openWs(port);
       const res = await connectReq(ws, {

src/gateway/server/ws-connection/message-handler.ts

@@ -66,19 +66,34 @@ function formatGatewayAuthFailureMessage(params: {
   authMode: ResolvedGatewayAuth["mode"];
   authProvided: AuthProvidedKind;
   reason?: string;
+  client?: { id?: string | null; mode?: string | null };
 }): string {
-  const { authMode, authProvided, reason } = params;
+  const { authMode, authProvided, reason, client } = params;
+  const isCli = isGatewayCliClient(client);
+  const isControlUi = client?.id === GATEWAY_CLIENT_IDS.CONTROL_UI;
+  const isWebchat = isWebchatClient(client);
+  const uiHint = "open a tokenized dashboard URL or paste token in Control UI settings";
+  const tokenHint = isCli
+    ? "set gateway.remote.token to match gateway.auth.token"
+    : isControlUi || isWebchat
+      ? uiHint
+      : "provide gateway auth token";
+  const passwordHint = isCli
+    ? "set gateway.remote.password to match gateway.auth.password"
+    : isControlUi || isWebchat
+      ? "enter the password in Control UI settings"
+      : "provide gateway auth password";
   switch (reason) {
     case "token_missing":
-      return "unauthorized: gateway token missing (set gateway.remote.token to match gateway.auth.token)";
+      return `unauthorized: gateway token missing (${tokenHint})`;
     case "token_mismatch":
-      return "unauthorized: gateway token mismatch (set gateway.remote.token to match gateway.auth.token)";
+      return `unauthorized: gateway token mismatch (${tokenHint})`;
     case "token_missing_config":
       return "unauthorized: gateway token not configured on gateway (set gateway.auth.token)";
     case "password_missing":
-      return "unauthorized: gateway password missing (set gateway.remote.password to match gateway.auth.password)";
+      return `unauthorized: gateway password missing (${passwordHint})`;
     case "password_mismatch":
-      return "unauthorized: gateway password mismatch (set gateway.remote.password to match gateway.auth.password)";
+      return `unauthorized: gateway password mismatch (${passwordHint})`;
     case "password_missing_config":
       return "unauthorized: gateway password not configured on gateway (set gateway.auth.password)";
     case "tailscale_user_missing":
@@ -90,10 +105,10 @@ function formatGatewayAuthFailureMessage(params: {
   }
 
   if (authMode === "token" && authProvided === "none") {
-    return "unauthorized: gateway token missing (set gateway.remote.token to match gateway.auth.token)";
+    return `unauthorized: gateway token missing (${tokenHint})`;
   }
   if (authMode === "password" && authProvided === "none") {
-    return "unauthorized: gateway password missing (set gateway.remote.password to match gateway.auth.password)";
+    return `unauthorized: gateway password missing (${passwordHint})`;
   }
   return "unauthorized";
 }
@@ -532,6 +547,7 @@ export function attachGatewayWsMessageHandler(params: {
             authMode: resolvedAuth.mode,
             authProvided,
             reason: authResult.reason,
+            client: connectParams.client,
           });
           setCloseCause("unauthorized", {
             authMode: resolvedAuth.mode,

src/signal/monitor.tool-result.sends-tool-summaries-responseprefix.test.ts

@@ -126,6 +126,90 @@ describe("monitorSignalProvider tool results", () => {
       }),
     );
   });
+
+  it("uses startupTimeoutMs override when provided", async () => {
+    const runtime = {
+      log: vi.fn(),
+      error: vi.fn(),
+      exit: ((code: number): never => {
+        throw new Error(`exit ${code}`);
+      }) as (code: number) => never,
+    };
+    config = {
+      ...config,
+      channels: {
+        ...config.channels,
+        signal: {
+          autoStart: true,
+          dmPolicy: "open",
+          allowFrom: ["*"],
+          startupTimeoutMs: 60_000,
+        },
+      },
+    };
+    const abortController = new AbortController();
+    streamMock.mockImplementation(async () => {
+      abortController.abort();
+      return;
+    });
+
+    await monitorSignalProvider({
+      autoStart: true,
+      baseUrl: "http://127.0.0.1:8080",
+      abortSignal: abortController.signal,
+      runtime,
+      startupTimeoutMs: 90_000,
+    });
+
+    expect(waitForTransportReadyMock).toHaveBeenCalledTimes(1);
+    expect(waitForTransportReadyMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        timeoutMs: 90_000,
+      }),
+    );
+  });
+
+  it("caps startupTimeoutMs at 2 minutes", async () => {
+    const runtime = {
+      log: vi.fn(),
+      error: vi.fn(),
+      exit: ((code: number): never => {
+        throw new Error(`exit ${code}`);
+      }) as (code: number) => never,
+    };
+    config = {
+      ...config,
+      channels: {
+        ...config.channels,
+        signal: {
+          autoStart: true,
+          dmPolicy: "open",
+          allowFrom: ["*"],
+          startupTimeoutMs: 180_000,
+        },
+      },
+    };
+    const abortController = new AbortController();
+    streamMock.mockImplementation(async () => {
+      abortController.abort();
+      return;
+    });
+
+    await monitorSignalProvider({
+      autoStart: true,
+      baseUrl: "http://127.0.0.1:8080",
+      abortSignal: abortController.signal,
+      runtime,
+    });
+
+    expect(waitForTransportReadyMock).toHaveBeenCalledTimes(1);
+    expect(waitForTransportReadyMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        timeoutMs: 120_000,
+      }),
+    );
+  });
+
   it("sends tool summaries with responsePrefix", async () => {
     const abortController = new AbortController();
     replyMock.mockImplementation(async (_ctx, opts) => {

src/signal/monitor.ts

@@ -43,6 +43,7 @@ export type MonitorSignalOpts = {
   config?: ClawdbotConfig;
   baseUrl?: string;
   autoStart?: boolean;
+  startupTimeoutMs?: number;
   cliPath?: string;
   httpHost?: string;
   httpPort?: number;
@@ -285,6 +286,10 @@ export async function monitorSignalProvider(opts: MonitorSignalOpts = {}): Promi
   const sendReadReceipts = Boolean(opts.sendReadReceipts ?? accountInfo.config.sendReadReceipts);
 
   const autoStart = opts.autoStart ?? accountInfo.config.autoStart ?? !accountInfo.config.httpUrl;
+  const startupTimeoutMs = Math.min(
+    120_000,
+    Math.max(1_000, opts.startupTimeoutMs ?? accountInfo.config.startupTimeoutMs ?? 30_000),
+  );
   const readReceiptsViaDaemon = Boolean(autoStart && sendReadReceipts);
   let daemonHandle: ReturnType<typeof spawnSignalDaemon> | null = null;
 
@@ -315,7 +320,7 @@ export async function monitorSignalProvider(opts: MonitorSignalOpts = {}): Promi
       await waitForSignalDaemonReady({
         baseUrl,
         abortSignal: opts.abortSignal,
-        timeoutMs: 30_000,
+        timeoutMs: startupTimeoutMs,
         logAfterMs: 10_000,
         logIntervalMs: 10_000,
         runtime,