let5see/clawdbot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add daemon service management

Browse Source
This commit is contained in:
Peter Steinberger
2026-01-07 21:37:05 +01:00
parent 7aeb6d5921
commit 391a3d6eaf
17 changed files with 1264 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
docs/cli/index.md
View File

@@ -362,6 +362,25 @@ Options:
### `gateway-daemon`
Run the Gateway as a long-lived daemon (same options as `gateway`, minus `--allow-unconfigured` and `--force`).
### `daemon`
Manage the Gateway service (launchd/systemd/schtasks).
Subcommands:
- `daemon status` (probes the Gateway RPC by default)
- `daemon install` (service install)
- `daemon uninstall`
- `daemon start`
- `daemon stop`
- `daemon restart`
Notes:
- `daemon status` uses the same URL/token defaults as `gateway status` unless you pass `--url/--token/--password`.
- `daemon status` supports `--no-probe`, `--deep`, and `--json` for scripting.
- `daemon status` also surfaces legacy or extra gateway services when it can detect them (`--deep` adds system-level scans).
- `daemon install` defaults to Node runtime; use `--runtime bun` only when WhatsApp is disabled.
- `daemon install` options: `--port`, `--runtime`, `--token`.
- `gateway install|uninstall|start|stop|restart` remain as service aliases; `daemon` is the dedicated manager.
### `gateway <subcommand>`
Gateway RPC helpers (use `--url`, `--token`, `--password`, `--timeout`, `--expect-final` for each).
@@ -372,8 +391,12 @@ Subcommands:
- `gateway wake --text <text> [--mode now|next-heartbeat]`
- `gateway send --to <jidOrPhone> --message <text> [--media-url <url>] [--gif-playback] [--idempotency-key <key>]`
- `gateway agent --message <text> [--to <jidOrPhone>] [--session-id <id>] [--thinking <level>] [--deliver] [--timeout-seconds <n>] [--idempotency-key <key>]`
- `gateway install`
- `gateway uninstall`
- `gateway start`
- `gateway stop`
- `gateway restart`
- `gateway daemon status` (alias for `clawdbot daemon status`)
## Models

16
docs/docs.json
View File

@@ -646,7 +646,17 @@
{
"group": "Platforms",
"pages": [
"platforms",
"platforms/macos",
"platforms/ios",
"platforms/android",
"platforms/windows",
"platforms/linux"
]
},
{
"group": "macOS Companion App",
"pages": [
"platforms/mac/dev-setup",
"platforms/mac/menu-bar",
"platforms/mac/voicewake",
@@ -664,11 +674,7 @@
"platforms/mac/bun",
"platforms/mac/xpc",
"platforms/mac/skills",
"platforms/mac/peekaboo",
"platforms/ios",
"platforms/android",
"platforms/windows",
"platforms/linux"
"platforms/mac/peekaboo"
]
},
{

19
docs/gateway/index.md
View File

@@ -157,6 +157,25 @@ See also: [`docs/presence.md`](/concepts/presence) for how presence is produced/
- On failure, launchd restarts; fatal misconfig should keep exiting so the operator notices.
- LaunchAgents are per-user and require a logged-in session; for headless setups use a custom LaunchDaemon (not shipped).
## Daemon management (CLI)
Use the CLI daemon manager for install/start/stop/restart/status:
```bash
clawdbot daemon status
clawdbot daemon install
clawdbot daemon stop
clawdbot daemon restart
```
Notes:
- `daemon status` probes the Gateway RPC by default (same URL/token defaults as `gateway status`).
- `daemon status --deep` adds system-level scans (LaunchDaemons/system units).
- `gateway install|uninstall|start|stop|restart` remain supported as aliases; `daemon` is the dedicated manager.
- `gateway daemon status` is an alias for `clawdbot daemon status`.
- If other gateway-like services are detected, the CLI warns. We recommend **one gateway per machine**; one gateway can host multiple agents.
- Cleanup: `clawdbot daemon uninstall` (current service) and `clawdbot doctor` (legacy migrations).
Bundled mac app:
- Clawdbot.app can bundle a bun-compiled gateway binary and install a per-user LaunchAgent labeled `com.clawdbot.gateway`.
- To stop it cleanly, use `clawdbot gateway stop` (or `launchctl bootout gui/$UID/com.clawdbot.gateway`).

9
docs/platforms/android.md
View File

@@ -8,6 +8,15 @@ read_when:
# Android App (Node)
## Support snapshot
- Role: companion node app (Android does not host the Gateway).
- Gateway required: yes (run it on macOS, Linux, or Windows via WSL2).
- Install: [Getting Started](/start/getting-started) + [Pairing](/gateway/pairing).
- Gateway: [Runbook](/gateway) + [Configuration](/gateway/configuration).
## System control
System control (launchd/systemd) lives on the Gateway host. See [Gateway](/gateway).
## Connection Runbook
Android node app ⇄ (mDNS/NSD + TCP bridge) ⇄ **Gateway bridge** ⇄ (loopback WS) ⇄ **Gateway**

40
docs/platforms/index.md Normal file
View File

@@ -0,0 +1,40 @@
---
summary: "Platform support overview (Gateway + companion apps)"
read_when:
- Looking for OS support or install paths
- Deciding where to run the Gateway
---
# Platforms
Clawdbot core is written in TypeScript, so the CLI + Gateway run anywhere Node or Bun runs.
Companion apps exist for macOS (menu bar app) and mobile nodes (iOS/Android). Windows and
Linux companion apps are planned, but the core Gateway is fully supported today.
## Choose your OS
- macOS: [macOS](/platforms/macos)
- iOS: [iOS](/platforms/ios)
- Android: [Android](/platforms/android)
- Windows: [Windows](/platforms/windows)
- Linux: [Linux](/platforms/linux)
## Common links
- Install guide: [Getting Started](/start/getting-started)
- Gateway runbook: [Gateway](/gateway)
- Gateway configuration: [Configuration](/gateway/configuration)
- Service status: `clawdbot daemon status`
## Gateway service install (CLI)
Use one of these (all supported):
- Wizard (recommended): `clawdbot onboard --install-daemon`
- Direct: `clawdbot daemon install` (alias: `clawdbot gateway install`)
- Configure flow: `clawdbot configure` → select **Gateway daemon**
- Repair/migrate: `clawdbot doctor` (offers to install or fix the service)
The service target depends on OS:
- macOS: LaunchAgent (`com.clawdbot.gateway`)
- Linux/WSL2: systemd user service

9
docs/platforms/ios.md
View File

@@ -12,6 +12,15 @@ read_when:
Status: prototype implemented (internal) · Date: 2025-12-13
## Support snapshot
- Role: companion node app (iOS does not host the Gateway).
- Gateway required: yes (run it on macOS, Linux, or Windows via WSL2).
- Install: [Getting Started](/start/getting-started) + [Pairing](/gateway/pairing).
- Gateway: [Runbook](/gateway) + [Configuration](/gateway/configuration).
## System control
System control (launchd/systemd) lives on the Gateway host. See [Gateway](/gateway).
## Connection Runbook
This is the practical “how do I connect the iOS node” guide:

73
docs/platforms/linux.md
View File

@@ -1,11 +1,80 @@
---
summary: "Linux app status + contribution call"
summary: "Linux support + companion app status"
read_when:
- Looking for Linux companion app status
- Planning platform coverage or contributions
---
# Linux App
Clawdbot core is fully supported on Linux. The core is written in TypeScript, so it runs anywhere Node runs.
Clawdbot core is fully supported on Linux. The core is written in TypeScript, so it runs anywhere Node or Bun runs.
We do not have a Linux companion app yet. It is planned, and we would love contributions to make it happen.
## Install
- [Getting Started](/start/getting-started)
- [Install & updates](/install/updating)
- Optional flows: [Bun](/install/bun), [Nix](/install/nix), [Docker](/install/docker)
## Gateway
- [Gateway runbook](/gateway)
- [Configuration](/gateway/configuration)
## Gateway service install (CLI)
Use one of these:
```
clawdbot onboard --install-daemon
```
Or:
```
clawdbot daemon install
```
Or:
```
clawdbot gateway install
```
Or:
```
clawdbot configure
```
Select **Gateway daemon** when prompted.
Repair/migrate:
```
clawdbot doctor
```
## System control (systemd user unit)
Full unit example lives in the [Gateway runbook](/gateway). Minimal setup:
Create `~/.config/systemd/user/clawdbot-gateway.service`:
```
[Unit]
Description=Clawdbot Gateway
After=network-online.target
Wants=network-online.target
[Service]
ExecStart=/usr/local/bin/clawdbot gateway --port 18789
Restart=always
RestartSec=5
[Install]
WantedBy=default.target
```
Enable it:
```
systemctl --user enable --now clawdbot-gateway.service
```

17
docs/platforms/macos.md
View File

@@ -8,6 +8,23 @@ read_when:
Author: steipete · Status: draft spec · Date: 2025-12-20
## Support snapshot
- Core Gateway: supported (TypeScript on Node/Bun).
- Companion app: macOS menu bar app with permissions + node bridge.
- Install: [Getting Started](/start/getting-started) or [Install & updates](/install/updating).
- Gateway: [Runbook](/gateway) + [Configuration](/gateway/configuration).
## System control (launchd)
If you run the bundled macOS app, it installs a per-user LaunchAgent labeled `com.clawdbot.gateway`.
CLI-only installs can use `clawdbot onboard --install-daemon`, `clawdbot daemon install`, or `clawdbot configure` → **Gateway daemon**.
```bash
launchctl kickstart -k gui/$UID/com.clawdbot.gateway
launchctl bootout gui/$UID/com.clawdbot.gateway
```
Details: [Gateway runbook](/gateway) and [Bundled bun Gateway](/platforms/mac/bun).
## Purpose
- Single macOS menu-bar app named **Clawdbot** that:
- Shows native notifications for Clawdbot/clawdbot events.

53
docs/platforms/windows.md
View File

@@ -1,5 +1,5 @@
---
summary: "Windows (WSL2) setup + companion app status"
summary: "Windows (WSL2) support + companion app status"
read_when:
- Installing Clawdbot on Windows
- Looking for Windows companion app status
@@ -7,14 +7,55 @@ read_when:
---
# Windows (WSL2)
Clawdbot runs on Windows **via WSL2** (Ubuntu recommended). WSL2 is **strongly
recommended**; native Windows installs are untested and more problematic. Use
WSL2 and follow the Linux flow inside it.
Clawdbot core is supported on Windows **via WSL2** (Ubuntu recommended). The
CLI + Gateway run inside Linux, which keeps the runtime consistent. Native
Windows installs are untested and more problematic.
## Install
- [Getting Started](/start/getting-started) (use inside WSL)
- [Install & updates](/install/updating)
- Official WSL2 guide (Microsoft): https://learn.microsoft.com/windows/wsl/install
## Gateway
- [Gateway runbook](/gateway)
- [Configuration](/gateway/configuration)
## Gateway service install (CLI)
Inside WSL2:
```
clawdbot onboard --install-daemon
```
Or:
```
clawdbot daemon install
```
Or:
```
clawdbot gateway install
```
Or:
```
clawdbot configure
```
Select **Gateway daemon** when prompted.
Repair/migrate:
```
clawdbot doctor
```
## How to install this correctly
Start here (official WSL2 guide): https://learn.microsoft.com/windows/wsl/install
### 1) Install WSL2 + Ubuntu
Open PowerShell (Admin):

16
docs/start/hubs.md
View File

@@ -114,7 +114,16 @@ Use these hubs to discover every page, including deep dives and reference docs t
## Platforms
- [macOS app overview](https://docs.clawd.bot/platforms/macos)
- [Platforms overview](https://docs.clawd.bot/platforms)
- [macOS](https://docs.clawd.bot/platforms/macos)
- [iOS](https://docs.clawd.bot/platforms/ios)
- [Android](https://docs.clawd.bot/platforms/android)
- [Windows (WSL2)](https://docs.clawd.bot/platforms/windows)
- [Linux](https://docs.clawd.bot/platforms/linux)
- [Web surfaces](https://docs.clawd.bot/web)
## macOS companion app (internals)
- [macOS dev setup](https://docs.clawd.bot/platforms/mac/dev-setup)
- [macOS menu bar](https://docs.clawd.bot/platforms/mac/menu-bar)
- [macOS voice wake](https://docs.clawd.bot/platforms/mac/voicewake)
@@ -133,11 +142,6 @@ Use these hubs to discover every page, including deep dives and reference docs t
- [macOS XPC](https://docs.clawd.bot/platforms/mac/xpc)
- [macOS skills](https://docs.clawd.bot/platforms/mac/skills)
- [macOS Peekaboo plan](https://docs.clawd.bot/platforms/mac/peekaboo)
- [iOS node](https://docs.clawd.bot/platforms/ios)
- [Android node](https://docs.clawd.bot/platforms/android)
- [Windows (WSL2)](https://docs.clawd.bot/platforms/windows)
- [Linux app](https://docs.clawd.bot/platforms/linux)
- [Web surfaces](https://docs.clawd.bot/web)
## Workspace + templates