Zo Mac Controller

An open-source, security-first bridge for controlling a Mac from Zo Computer. It combines a private coordinator, a native macOS menu-bar agent, and a simulator for testing the protocol without causing Mac side effects.

Warning

This is an independent community project, not an official Zo Computer or Apple product. It can control apps, files, input, screenshots, shell commands, and Messages after you explicitly enable those capabilities. Review the code and start in simulation mode.

What It Does

• Pairs each Mac with a short-lived code and a unique Ed25519 identity
• Keeps Mac connections outbound-only; no inbound Mac port is required
• Signs device requests and rejects stale or replayed requests
• Schedules idempotent tasks with approval gates for sensitive actions
• Uses atomic leases and explicit recovery instead of blindly retrying side effects
• Records append-only audit events
• Supports app, clipboard, bounded file, status, permission, Accessibility, input, and screen-capture actions
• Restricts real iMessage sending to explicitly enabled recipients
• Allows bounded shell diagnostics only after separate approval

Architecture

Zo / admin CLI -> private coordinator -> HTTPS relay <- signed Mac agent

The coordinator owns devices, tasks, approvals, execution leases, results, and audit history. The Mac agent stores its private key in Keychain and polls the relay over HTTPS. Administrative operations stay on localhost.

Quick Start

Requirements:

• A Zo Computer account
• Bun 1.2 or newer on the coordinator
• macOS 14 or newer with Xcode Command Line Tools

1. Start the coordinator

git clone https://github.com/gbarb18/zo-mac-controller.git
cd zo-mac-controller
bun install

export ZO_MAC_ADMIN_TOKEN="$(openssl rand -base64 32)"
export ZO_MAC_DB_PATH="$PWD/data/coordinator.sqlite"
bun run start

The coordinator binds to 127.0.0.1:4318 by default. Do not expose its /v1/* administrative endpoints to the internet.

2. Add the relay

Create a Zo Space API route at /api/mac-agent/:operation using examples/zo-space-relay.ts. The relay exposes only the seven signed agent operations and forwards them to the local coordinator.

See docs/deployment.md for the complete Zo setup and alternatives for self-hosting.

3. Pair a Mac

Generate a one-time pairing code on the coordinator:

bun run admin pairing-code

On the Mac:

cd mac-agent
./scripts/build-app.sh
./scripts/install-user.sh

Open the menu-bar app and enter your public Zo Space URL, a device name, its role, and the pairing code. The first pairing always runs in simulation mode.

Administration

The CLI reads ZO_MAC_ADMIN_TOKEN, or falls back to data/admin-token for local installations that manage the token as a file.

bun run admin devices
bun run admin audit 100
bun run admin task ./task.json
bun run admin approve <task-id>
bun run admin cancel <task-id>
bun run admin revoke <device-id>

Verification

bun test
bun run verify:e2e

bun run verify:deployed also checks a live relay. Set ZO_MAC_AGENT_URL to its public base URL before running it.

Security Defaults

• No Mac login password is stored.
• The coordinator refuses to start without an admin token of at least 24 characters.
• Device private keys remain in macOS Keychain.
• Every device request is signed and carries a one-time request ID.
• Sensitive tasks require separate approval before they can be claimed.
• Interrupted leases become recovery_required; they are never blindly replayed.
• Real actions start disabled and simulation mode remains the default-deny boundary.

Read SECURITY.md before enabling real capabilities. Security reports should not be filed as public issues.

Contributing

Contributions are welcome. Read CONTRIBUTING.md, run both Bun verification commands, and keep the security invariants intact.

Support The Project

If this project saves you time, you can support its maintenance through Venmo, Cash App, or Bitcoin. See SUPPORT.md for the verified payment details. The software remains free and MIT licensed regardless of support.

License

MIT Copyright 2026 gbarb18.