SYSTEM: A Cloud‑Hosted Natural‑Language Mac Remote Automation Platform

SYSTEM is a lightweight framework that lets you control any macOS device remotely through conversation, powered by Cloudflare Workers, Claude, and a lightweight local bridge. By separating the intelligence layer from the execution layer it delivers strong security guarantees, low latency, and rich integration with existing tools such as Raycast, Shortcuts, and native Apple scripting. The platform ships with a zero‑configuration “quick start” that walks developers through setting up authentication, installing Raycast extensions, and provisioning the bridge. Quick Start - Clone the repository and install dependencies: ``` git clone https://github.com/ygwyg/system cd system && npm install ``` - Run the interactive wizard: ``` npm run setup ``` During the wizard you will be prompted for an Anthropic API key, the location of any Raycast extensions, and whether the agent should expose a public tunnel. - Start the system: ``` npm start ``` This launches the Cloudflare tunnel, spins up the express bridge on port 3456, and opens the web UI at https://your-agent.workers.dev. Architecture ``` +---------------------------------------------------+ | User (phone/browser) | +---------------------+---------------------------+ | HTTPS v +---------------------------------------------------+ | AGENT (Brain) | | Cloudflare Workers + D.O. | | +--------+ +--------+ +--------+ | | |Claude | |State | |Schedules| | | +--------+ +--------+ +--------+ | +---------------------+---------------------------+ | Tunnel v +---------------------------------------------------+ | BRIDGE (Body) | | macOS local server | | +---------+ +---------+ +---------+ | | |AppleScript| |Shell | |Raycast | | | +---------+ +---------+ +---------+ | +---------------------------------------------------+ ``` The agent (brain) resides entirely in the Cloudflare Workers runtime, storing state and scheduling logic in Durable Objects. All communication with the bridge (body) occurs over a secure WebSocket tunnel that is established once a user authenticates with a bearer token. Authentication Every request to the agent API must present an API secret either as a ` Authorization: Bearer ` header or a `?token=` query parameter. Tokens are generated during the ` npm run setup` step and written to ` bridge.config.json`. Chat & Scheduling Send a natural‑language message to the agent via the UI or an HTTP POST: ```http POST https://your-agent.workers.dev/chat Bearer { \"message\": \"Play some jazz music\" } ``` The agent replies with an intent‑driven JSON that lists both a human‑readable confirmation message and the low‑level tool actions it will perform, for example: ```json { \"message\": \"Playing jazz on Apple Music\", \"actions\": [{ \"tool\": \"music_play\", \"args\": { \"query\": \"jazz\" }, \"success\": true, \"result\": \"Now playing: Jazz Vibes\" }] } ``` You can also cancel or list scheduled tasks, clear history, or retrieve the current agent state using the corresponding endpoints. Core Toolset SYSTEM ships with a rich set of pre‑defined tools that can be invoked autonomously or via Raycast extensions. Some of the most frequently used include: * `open_app` – Launch any native application. * `open_url` – Open a URL in the default browser. * `shell` – Execute a whitelist‑protected shell command. * `applescript` – Run arbitrary AppleScript. * `notify` – Show a macOS notification. * `say` – Text‑to‑speech via `say(1)`. * `clipboard_get/set` – Read or write the clipboard. * `screenshot` – Capture a screenshot and store it locally. Music, Messaging, and System Utilities The platform also contains specialized tool families for Apple Music control (`music_play`, `music_pause`, etc.), iMessage sending (`send_imessage`), calendar and reminders manipulation, display settings, battery status, notes, and file operations via Finder. Raycast Integration During setup, SYSTEM scans `~/.config/raycast/extensions/` and exposes every compatible command as a distinct tool. The generic name follows the pattern `extension_command`, e.g. `spotify_player_play` or `linear_create_issue_for_myself`. Users can then issue natural‑language requests such as “Create a Linear issue for fixing the login bug” or “Send a Slack message to #general saying hello”. Bridge API For advanced integration, the bridge exposes a local REST API that lists all available tools, executes a chosen tool with arguments, or reports bridge status. Sample GET to list tools: ```http GET http://localhost:3456/api/tools Bearer ``` WebSocket Events Clients can subscribe to live notifications (e.g. task results, scheduled runs) via the WebSocket endpoint: ```javascript const ws = new WebSocket('wss://your-agent.workers.dev/ws?token=...'); ws.onmessage = e => { const payload = JSON.parse(e.data); console.log(payload.type, payload.payload); }; ``` Security Model * **Bearer tokens** – The only credential for API access, stored securely on the local bridge and never transmitted unencrypted. * **Shell safety** – The bridge accepts only a curated whitelist of shell commands; anything resembling `rm -rf` or `sudo` is blocked. * **Ephemeral tunnels** – Cloudflare Tunnel creates a new short‑lived URL for each session, and the local bridge listens only when a tunnel is active. * **Human‑in‑the‑loop** – Sensitive operations like sending messages prompt the user for confirmation before execution. Zero Trust Deployment For production deployments, we recommend enabling Cloudflare Access to add an extra authentication layer at the edge. The Access application can be deployed via the Cloudflare dashboard or Terraform. An example Terraform snippet: ```hcl resource \"cloudflare_access_application\" \"system\" { zone_id = var.zone_id name = \"SYSTEM\" domain = \"your‑agent.workers.dev\" session_duration = \"24h\" } resource \"cloudflare_access_policy\" \"allow_me\" { application_id = cloudflare_access_application.system.id zone_id = var.zone_id name = \"Allow specific emails\" precedence = 1 decision = \"allow\" include { email = [\"you@example.com\"] } } ``` Conclusion SYSTEM blends the scalability of Cloudflare Workers with the immediateness of local macOS controls, all through a conversational interface. Its design prioritises security, extensibility, and developer ergonomics, making it an ideal foundation for building advanced, multi‑device automation workflows.