macOS Client (Clawdbot)
Relevant source files
The following files were used as context for generating this wiki page:
The Clawdbot macOS client is a native application designed to provide a seamless interface for interacting with the Clawdbot gateway and its various agents. It serves as a primary user interface (UI) surface, offering specialized capabilities such as the Canvas for visual content rendering, menu bar integration for status monitoring, and native execution environments for coding agents.
Sources: CLAUDE.md:104, skills/canvas/SKILL.md:5-10, package.json:96-98
Architecture and Core Components
The macOS client operates as a node within the larger Clawdbot ecosystem, connecting to a Node Bridge via TCP. It acts as a bridge between the local system resources and the AI agents, allowing agents to perform actions like screen recording, file manipulation, and web content presentation.
Node Communication Flow
The client communicates with the Gateway through a multi-layered server architecture to handle different data types (e.g., control commands vs. web assets).
The diagram shows how the macOS client receives control signals from the Node Bridge while fetching visual assets directly from the Canvas Host.
Sources: skills/canvas/SKILL.md:20-30
Technical Specifications
| Component | Description | Reference |
|---|---|---|
| Minimum OS | macOS 15.0 | appcast.xml:8 |
| Connection Port | 18790 (Node Bridge TCP) | skills/canvas/SKILL.md:23 |
| Canvas Port | 18793 (HTTP Server) | skills/canvas/SKILL.md:22 |
| Language | Swift (for native app components) | package.json:118-120 |
| Runtime | Node.js 22+ (for background CLI tools) | CLAUDE.md:104 |
Key Features
The Canvas System
The Canvas is a specialized WebView component that allows agents to display HTML/CSS/JS content directly on the macOS desktop. It supports interactive visualizations, dashboards, and games.
- Present: Agents can command the macOS client to show a specific URL or raw HTML content.
- Eval: Agents can execute JavaScript directly within the running Canvas session.
- Snapshot: Captures a screenshot of the current Canvas state for visual analysis.
Sources: skills/canvas/SKILL.md:43-51, apps/macos/Tests/ClawdbotIPCTests/LowCoverageHelperTests.swift:150-160
Coding Agent Integration
The macOS client provides a native environment for running coding agents like Codex and Claude Code. It supports allocating a pseudo-terminal (PTY) to ensure interactive CLI tools render correctly with full color and input support.
This sequence demonstrates the execution of coding tasks through a PTY-enabled shell on macOS.
Sources: skills/coding-agent/SKILL.md:10-25, apps/macos/Tests/ClawdbotIPCTests/LowCoverageHelperTests.swift:45-55
Menu Bar and Presence
The client integrates into the macOS menu bar to provide quick access to settings and status. It includes a PresenceReporter that communicates the local machine's status, including IP addresses, app version, and platform details to the Gateway.
Sources: apps/macos/Tests/ClawdbotIPCTests/LowCoverageHelperTests.swift:105-115, appcast.xml:240
Configuration and Setup
Configuration for the macOS client is largely driven by the ~/.clawdbot/clawdbot.json file on the host machine.
Canvas Configuration Example
{
"canvasHost": {
"enabled": true,
"port": 18793,
"root": "/Users/user/clawd/canvas",
"liveReload": true
},
"gateway": {
"bind": "auto"
}
}
Sources: skills/canvas/SKILL.md:53-65
Connectivity Options
The client's ability to receive commands depends on how the Gateway is bound.
- Tailnet: Uses Tailscale hostnames, allowing remote agents to control the macOS UI securely.
- LAN: Uses local IP addresses for control within the same network.
- Loopback: Restricted to the local machine only.
Sources: skills/canvas/SKILL.md:32-41
Development and Packaging
The macOS app is managed using xcodegen and xcodebuild.
- Generate Project:
pnpm ios:gen(utilizes xcodegen). - Build App:
pnpm ios:build. - Package for Distribution:
scripts/package-mac-app.sh. - Restart Utility:
scripts/restart-mac.sh.
Sources: package.json:96-104, CLAUDE.md:104
Summary
The macOS Client (Clawdbot) is a critical UI and execution node in the Clawdbot network. By combining native Swift components for UI (Canvas, Menu Bar) with robust shell execution capabilities (PTY, Coding Agents), it enables complex, visually-rich workflows that bridge the gap between AI reasoning and local system interaction.