docs: remove legacy bundled gateway doc
This commit is contained in:
Peter Steinberger
@@ -1,114 +0,0 @@
|
||||
---
|
||||
summary: "Bundled Node gateway: packaging, launchd, signing, and bundling"
|
||||
read_when:
|
||||
- Packaging Clawdbot.app
|
||||
- Debugging the bundled gateway binary
|
||||
- Changing relay bundling flags or codesigning
|
||||
---
|
||||
|
||||
# Bundled Node Gateway (macOS)
|
||||
|
||||
Goal: ship **Clawdbot.app** with a self-contained relay that can run the CLI and
|
||||
Gateway daemon. No global `npm install -g clawdbot`, no system Node requirement.
|
||||
|
||||
## What gets bundled
|
||||
|
||||
App bundle layout:
|
||||
|
||||
- `Clawdbot.app/Contents/Resources/Relay/node`
|
||||
- Node runtime binary (downloaded during packaging, stripped for size)
|
||||
- `Clawdbot.app/Contents/Resources/Relay/dist/`
|
||||
- Compiled CLI/gateway payload from `pnpm exec tsc`
|
||||
- `Clawdbot.app/Contents/Resources/Relay/node_modules/`
|
||||
- Production dependencies staged via `pnpm deploy --prod --no-optional --legacy`
|
||||
- `Clawdbot.app/Contents/Resources/Relay/clawdbot`
|
||||
- Wrapper script that execs the bundled Node + dist entrypoint
|
||||
- `Clawdbot.app/Contents/Resources/Relay/package.json`
|
||||
- tiny “Pi runtime compatibility” file (see below, includes `"type": "module"`)
|
||||
- `Clawdbot.app/Contents/Resources/Relay/skills/`
|
||||
- Bundled skills payload (required for Pi tools)
|
||||
- `Clawdbot.app/Contents/Resources/Relay/theme/`
|
||||
- Pi TUI theme payload (optional, but strongly recommended)
|
||||
- `Clawdbot.app/Contents/Resources/Relay/a2ui/`
|
||||
- A2UI host assets (served by the gateway)
|
||||
- `Clawdbot.app/Contents/Resources/Relay/control-ui/`
|
||||
- Control UI build output (served by the gateway)
|
||||
|
||||
Why the sidecar files matter:
|
||||
- The embedded Pi runtime detects “bundled relay mode” and then looks for
|
||||
`package.json` + `theme/` **next to `process.execPath`** (i.e. next to
|
||||
`node`). Keep the sidecar files.
|
||||
|
||||
## Build pipeline
|
||||
|
||||
Packaging script:
|
||||
- [`scripts/package-mac-app.sh`](https://github.com/clawdbot/clawdbot/blob/main/scripts/package-mac-app.sh)
|
||||
|
||||
It builds:
|
||||
- TS: `pnpm exec tsc`
|
||||
- Swift app + helper: `swift build …`
|
||||
- Relay payload: `pnpm deploy --prod --no-optional --legacy` + copy `dist/`
|
||||
- Node runtime: downloads the latest Node release (override via `NODE_VERSION`)
|
||||
|
||||
Important knobs:
|
||||
- `NODE_VERSION=22.12.0` → pin a specific Node version
|
||||
- `NODE_DIST_MIRROR=…` → mirror for downloads (default: nodejs.org)
|
||||
- `STRIP_NODE=0` → keep symbols (default strips to reduce size)
|
||||
- `BUNDLED_RUNTIME=bun` → switch the relay build back to Bun (`bun --compile`)
|
||||
|
||||
Version injection:
|
||||
- The relay wrapper exports `CLAWDBOT_BUNDLED_VERSION` so `--version` works
|
||||
without reading `package.json` at runtime.
|
||||
|
||||
## Launchd (Gateway as LaunchAgent)
|
||||
|
||||
Label:
|
||||
- `com.clawdbot.gateway`
|
||||
|
||||
Plist location (per-user):
|
||||
- `~/Library/LaunchAgents/com.clawdbot.gateway.plist`
|
||||
|
||||
Manager:
|
||||
- The macOS app owns LaunchAgent install/update for the bundled gateway.
|
||||
|
||||
Behavior:
|
||||
- “Clawdbot Active” enables/disables the LaunchAgent.
|
||||
- App quit does **not** stop the gateway (launchd keeps it alive).
|
||||
- CLI install (`clawdbot daemon install`) writes the same LaunchAgent; `--force` rewrites it.
|
||||
|
||||
Logging:
|
||||
- launchd stdout/err: `/tmp/clawdbot/clawdbot-gateway.log`
|
||||
|
||||
Default LaunchAgent env:
|
||||
- `CLAWDBOT_IMAGE_BACKEND=sips` (avoid sharp native addon inside the bundle)
|
||||
|
||||
## Codesigning (hardened runtime + Node)
|
||||
|
||||
Node uses JIT. The bundled runtime is signed with:
|
||||
- `com.apple.security.cs.allow-jit`
|
||||
- `com.apple.security.cs.allow-unsigned-executable-memory`
|
||||
|
||||
This is applied by `scripts/codesign-mac-app.sh`.
|
||||
|
||||
## Image processing
|
||||
|
||||
To avoid shipping native `sharp` addons inside the bundle, the gateway defaults
|
||||
to `/usr/bin/sips` for image ops when run from the app (via launchd env + wrapper).
|
||||
|
||||
## Tests / smoke checks
|
||||
|
||||
From a packaged app (local build):
|
||||
|
||||
```bash
|
||||
dist/Clawdbot.app/Contents/Resources/Relay/clawdbot --version
|
||||
|
||||
CLAWDBOT_SKIP_PROVIDERS=1 \
|
||||
CLAWDBOT_SKIP_CANVAS_HOST=1 \
|
||||
dist/Clawdbot.app/Contents/Resources/Relay/clawdbot gateway --port 18999 --bind loopback
|
||||
```
|
||||
|
||||
Then, in another shell:
|
||||
|
||||
```bash
|
||||
pnpm -s clawdbot gateway call health --url ws://127.0.0.1:18999 --timeout 3000
|
||||
```
|
||||
Reference in New Issue
Block a user