From 5ec499e14ce052581fa71c5952739b329607a6ac Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sun, 18 Jan 2026 16:29:33 +0000 Subject: [PATCH] docs: clarify mac gateway launch behavior --- docs/platforms/mac/bundled-gateway.md | 7 +++++-- docs/platforms/mac/child-process.md | 8 +++++--- docs/platforms/macos.md | 10 +++++----- 3 files changed, 15 insertions(+), 10 deletions(-) diff --git a/docs/platforms/mac/bundled-gateway.md b/docs/platforms/mac/bundled-gateway.md index ef11dcc14..c9d2b9c0d 100644 --- a/docs/platforms/mac/bundled-gateway.md +++ b/docs/platforms/mac/bundled-gateway.md @@ -9,8 +9,9 @@ read_when: # Gateway on macOS (external launchd) Clawdbot.app no longer bundles Node/Bun or the Gateway runtime. The macOS app -expects an **external** `clawdbot` CLI install and manages a per‑user launchd -service to keep the Gateway running. +expects an **external** `clawdbot` CLI install, does not spawn the Gateway as a +child process, and manages a per‑user launchd service to keep the Gateway +running (or attaches to an existing local Gateway if one is already running). ## Install the CLI (required for local mode) @@ -38,6 +39,8 @@ Manager: Behavior: - “Clawdbot Active” enables/disables the LaunchAgent. - App quit does **not** stop the gateway (launchd keeps it alive). +- If a Gateway is already running on the configured port, the app attaches to + it instead of starting a new one. Logging: - launchd stdout/err: `/tmp/clawdbot/clawdbot-gateway.log` diff --git a/docs/platforms/mac/child-process.md b/docs/platforms/mac/child-process.md index 584ba00e9..b88b0dece 100644 --- a/docs/platforms/mac/child-process.md +++ b/docs/platforms/mac/child-process.md @@ -5,9 +5,11 @@ read_when: --- # Gateway lifecycle on macOS -The macOS app **manages the Gateway via launchd** by default. The launchd job -uses the external `clawdbot` CLI (no embedded runtime). This gives you reliable -auto‑start at login and restart on crashes. +The macOS app **manages the Gateway via launchd** by default and does not spawn +the Gateway as a child process. It first tries to attach to an already‑running +Gateway on the configured port; if none is reachable, it enables the launchd +service via the external `clawdbot` CLI (no embedded runtime). This gives you +reliable auto‑start at login and restart on crashes. Child‑process mode (Gateway spawned directly by the app) is **not in use** today. If you need tighter coupling to the UI, run the Gateway manually in a terminal. diff --git a/docs/platforms/macos.md b/docs/platforms/macos.md index d9ea2a360..2c8466e6c 100644 --- a/docs/platforms/macos.md +++ b/docs/platforms/macos.md @@ -7,8 +7,8 @@ read_when: # Clawdbot macOS Companion (menu bar + gateway broker) The macOS app is the **menu‑bar companion** for Clawdbot. It owns permissions, -manages the Gateway locally, and exposes macOS capabilities to the agent as a -node. +manages/attaches to the Gateway locally (launchd or manual), and exposes macOS +capabilities to the agent as a node. ## What it does @@ -26,11 +26,11 @@ Planned: ## Local vs remote mode -- **Local** (default): the app ensures a local Gateway is running via launchd. +- **Local** (default): the app attaches to a running local Gateway if present; + otherwise it enables the launchd service via `clawdbot daemon`. - **Remote**: the app connects to a Gateway over SSH/Tailscale and never starts a local process. -- **Attach‑only** (debug): the app connects to an already‑running local Gateway - and never spawns its own. +The app does not spawn the Gateway as a child process. ## Launchd control