clawdbot/docs/platforms/mac/bun.md

summary, read_when

summary	read_when
Bundled bun gateway: packaging, launchd, signing, and bytecode	Packaging Clawdbot.app Debugging the bundled gateway binary Changing bun build flags or codesigning

Bundled bun Gateway (macOS)

Goal: ship Clawdbot.app with a self-contained relay binary that can run both the CLI and the Gateway daemon. No global npm install -g clawdbot, no system Node requirement.

What gets bundled

App bundle layout:

• Clawdbot.app/Contents/Resources/Relay/clawdbot
  • bun --compile relay executable built from dist/macos/relay.js
  • Supports:
    • clawdbot … (CLI)
    • clawdbot gateway … (LaunchAgent daemon)
• Clawdbot.app/Contents/Resources/Relay/package.json
  • tiny “p runtime compatibility” file (see below)
• Clawdbot.app/Contents/Resources/Relay/theme/
  • p TUI theme payload (optional, but strongly recommended)

Why the sidecar files matter:

• The embedded p runtime detects “bun binary mode” and then looks for package.json + theme/ next to process.execPath (i.e. next to clawdbot).
• So even if bun can embed assets, the runtime expects filesystem paths. Keep the sidecar files.

Build pipeline

Packaging script:

• scripts/package-mac-app.sh

It builds:

• TS: pnpm exec tsc
• Swift app + helper: swift build …
• bun relay: bun build dist/macos/relay.js --compile --bytecode …

Important bundler flags:

• --compile: produces a standalone executable
• --bytecode: reduces startup time / parsing overhead (works here)
• externals:
  • -e electron
  • Reason: avoid bundling Electron stubs in the relay binary

Version injection:

• --define "__CLAWDBOT_VERSION__=\"<pkg version>\""
• The relay honors __CLAWDBOT_VERSION__ / CLAWDBOT_BUNDLED_VERSION so --version doesn’t depend on 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; clawdbot daemon install --force rewrites it.
• clawdbot doctor audits the LaunchAgent config and can update it to current defaults.

Logging:

• launchd stdout/err: /tmp/clawdbot/clawdbot-gateway.log

Default LaunchAgent env:

• CLAWDBOT_IMAGE_BACKEND=sips (avoid sharp native addon under bun)

Codesigning (hardened runtime + bun)

Symptom (when mis-signed):

• Ran out of executable memory … on launch

Fix:

• The bun executable needs JIT-ish permissions under hardened runtime.
• scripts/codesign-mac-app.sh signs Relay/clawdbot with:
  • com.apple.security.cs.allow-jit
  • com.apple.security.cs.allow-unsigned-executable-memory

Image processing under bun

Problem:

• bun can’t load some native Node addons like sharp (and we don’t want to ship native addon trees for the gateway).

Solution:

• Image operations prefer /usr/bin/sips on macOS (especially under bun).
• When running in Node/dev, sharp is used when available.
• This affects inbound/outbound media, screenshots, and tool image sanitization.

Browser control server

The Gateway starts the browser control server (loopback only) from the relay daemon process, so the relay binary includes Playwright deps.

Tests / smoke checks

From a packaged app (local build):

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:

pnpm -s clawdbot gateway call health --url ws://127.0.0.1:18999 --timeout 3000

Repo hygiene

Bun may leave dotfiles like *.bun-build in the repo root or subfolders.

• These are ignored via .gitignore (*.bun-build).

DMG styling (human installer)

scripts/create-dmg.sh styles the DMG via Finder AppleScript.

Rules of thumb:

• Use a 72dpi background image that matches the Finder window size in points.
• Preferred asset: assets/dmg-background-small.png (500×320).
• Default icon positions: app {125,160}, Applications {375,160}.