remote mac automation

Control your Mac from anywhere using natural language. Built with Cloudflare Agents SDK for intelligent scheduling, memory, and tool orchestration.

quick start

1. clone and install

git clone https://github.com/ygwyg/system
cd system && npm install

2. run setup wizard

npm run setup

Interactive setup: Anthropic API key, Raycast extensions, remote access.

3. start system

npm start

Starts bridge, tunnel, and opens the agent UI.

architecture

SYSTEM uses a split architecture for security: the Agent (brain) runs on Cloudflare Workers, while the Bridge (body) runs locally on your Mac.

┌───────────────────────────────────────────────────────┐
│                        USER                           │
│                    (phone/browser)                    │
└─────────────────────┬─────────────────────────────────┘
                      │ HTTPS
                      ▼
┌───────────────────────────────────────────────────────┐
│                  AGENT (Brain)                        │
│              Cloudflare Workers                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │   Claude    │  │   State     │  │  Schedules  │    │
│  │     AI      │  │  (D.O.)     │  │   (D.O.)    │    │
│  └─────────────┘  └─────────────┘  └─────────────┘    │
└─────────────────────┬─────────────────────────────────┘
                      │ Tunnel
                      ▼
┌───────────────────────────────────────────────────────┐
│                  BRIDGE (Body)                        │
│                Your Mac (local)                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │ AppleScript │  │    Shell    │  │   Raycast   │    │
│  └─────────────┘  └─────────────┘  └─────────────┘    │
└───────────────────────────────────────────────────────┘

authentication

All requests require an API secret via Bearer token or query parameter.

Authorization: Bearer <api_secret>


?token=<api_secret>

chat

Send natural language commands to control your Mac.

{
  "message": "Play some jazz music"
}

{
  "message": "Playing jazz on Apple Music",
  "actions": [{
    "tool": "music_play",
    "args": { "query": "jazz" },
    "success": true,
    "result": "Now playing: Jazz Vibes"
  }]
}

schedules

Schedule one-time or recurring tasks using natural language or cron syntax.

{
  "schedules": [{
    "id": "abc123",
    "description": "Play closing time",
    "scheduledAt": "2026-01-05T17:00:00Z",
    "cron": "0 17 * * *"
  }]
}

state

The agent maintains persistent state including preferences and conversation history.

{
  "preferences": { "wife": "Jane" },
  "historyLength": 12,
  "scheduleCount": 2
}

core tools

Foundational tools for Mac automation.

music

Control Apple Music playback.

messaging

Send iMessages with human-in-the-loop confirmation.

system

Control system settings, get status, manage files and apps.

calendar & reminders

display & focus

system status

notes

Read and write Apple Notes.

files

Search and manage files via Finder.

shortcuts

Run Apple Shortcuts.

browser

Get info from Safari, Chrome, Arc, or other browsers.

raycast extensions

Execute Raycast extensions for powerful integrations. SYSTEM scans your installed extensions and makes them available as tools.

how it works

During npm run setup, SYSTEM scans your Raycast extensions folder and presents compatible commands for you to enable. Each enabled command becomes a dedicated tool.

Raycast Extension              SYSTEM Tool
─────────────────              ───────────
spotify-player/play      →     spotify_play
linear/create-issue      →     linear_create_issue
slack/send-message       →     slack_send_message

extension discovery

SYSTEM looks in ~/.config/raycast/extensions/ and reads each extension's package.json to find commands. Only commands with mode: "no-view" or mode: "view" are compatible.

compatible extension types

popular extensions that work well

tool naming

Tools are named as {extension}_{command} with hyphens replaced by underscores:

Tool name: linear_create_issue_for_myself


Tool name: spotify_player_play

using raycast tools

Once enabled, just ask naturally:

• "Create a Linear issue for fixing the login bug"
• "Send a Slack message to #general saying hello"
• "Play Daft Punk on Spotify"
• "Add 'buy groceries' to my Todoist"

generic raycast tool

For extensions not in your enabled list, use the generic raycast tool:

{
  "extension": "spotify-player",
  "command": "play",
  "arguments": { "query": "jazz" }
}

deep link format

Under the hood, SYSTEM uses Raycast deep links:

raycast://extensions/{author}/{extension}/{command}?arguments={json}

troubleshooting

re-scanning extensions

If you install new Raycast extensions, run setup again to add them:

npm run setup

Your existing configuration will be preserved—you'll just see new extensions to enable.

bridge api

Direct API to the local bridge. Used by the agent, but also available for custom integrations.

{
  "tool": "open_app",
  "args": { "app": "Safari" }
}

websocket

Real-time updates for scheduled tasks and notifications.

const ws = new WebSocket('wss://your-agent.workers.dev/ws?token=...');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  
  console.log(data.type, data.payload);
};

security

SYSTEM is designed with security as a priority.

cloudflare access (recommended)

If you deploy to Cloudflare Workers, add Cloudflare Access for Zero Trust authentication at the edge — before requests even reach your agent.

setup via dashboard

1. Go to Cloudflare Zero Trust Dashboard
2. Navigate to Access → Applications → Add an application
3. Select Self-hosted and enter your worker URL
4. Create an access policy (e.g., email = [email protected])
5. Save — users must now authenticate before accessing SYSTEM

automation (terraform)

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 = ["[email protected]"]
  }
}