Macapad

Control your Mac from your phone, a tablet, or a screen on the wall.

1. Install it

   Paste this into Terminal on your Mac.

   curl -fsSL https://raw.githubusercontent.com/AD-Archer/Macapad/main/scripts/install.sh | bash

   Takes a few minutes the first time. Run it again any time to update.

   What does it do?

   It downloads the latest release, builds it on your Mac, and puts it in Applications. Because your Mac built it, macOS opens it with no warnings and keeps its permissions when you update.

   It needs Apple’s Command Line Tools. If you don’t have them, their installer opens. Finish it, then run the command again.

   Needs an Apple Silicon Mac on macOS 14 or later. Rather use Homebrew or a download?

2. Let it press keys

   A smiling face appears in the menu bar. Then open System Settings → Privacy & Security → Accessibility and turn on Macapad.

3. Connect a device

   Pick a Mac. You’ll confirm on the Mac.

Apps for it

Other ways to install

The one command is easiest. These work too, with one extra step.

Homebrew

brew tap ad-archer/tap
brew trust ad-archer/tap
brew install --cask macapad
xattr -dr com.apple.quarantine /Applications/Macapad.app

To update: brew upgrade --cask macapad, then the xattr line again.

brew trust --cask ad-archer/tap/macapad

Download

1. Download Macapad.zip from Releases.
2. Unzip it and drag Macapad.app to Applications.
3. Run this in Terminal:

xattr -dr com.apple.quarantine /Applications/Macapad.app

Build it yourself

You need the Command Line Tools (xcode-select --install) and just (brew install just).

git clone https://github.com/AD-Archer/Macapad.git
cd Macapad
just cert      # once
just install

curl -fsSL https://raw.githubusercontent.com/AD-Archer/Macapad/main/scripts/install.sh | MACAPAD_REF=main bash

Pairing

How a device gets its own token. Use a QR code if it has a camera, or a 4-digit code if not.

With a QR code

No prompt on the Mac: seeing its screen is the proof.

1. On the Mac, choose Pair with QR Code… in the menu bar.
2. Scan it. It holds a link:

   macapad://pair?v=1&id=<mac id>&name=<mac name>&key=<one-time key>
     &url=http://192.168.1.20:7317
     &url=http://100.101.102.103:7317

3. Try each url in order and use the first that answers GET /api/health.
4. Trade the key for a token:

   POST <url>/api/pair/qr
   {"key": "<one-time key>", "name": "Kitchen iPad", "app": "archersdesk"}
   
   → {"status": "approved", "token": "…", "device": {…}, "mac": {"id": "…", "name": "…"}}

With a code

The Mac asks before allowing anything.

1. POST /api/pair with {"name": "Kitchen iPad", "app": "archersdesk"}. You get {"id", "code", "expiresIn", "mac"}.
2. Show the 4-digit code. The Mac shows the same code with Allow and Don’t Allow.
3. Poll GET /api/pair/<id>?wait=25. Each call waits up to 25 seconds, then returns pending, approved (with token and device), denied or expired.

Finding Macs

• Same Wi-Fi: Bonjour, _macapad._tcp. The TXT record has id, name and v.
• Tailscale: no Bonjour there. List devices with tailscale status --json and call /api/health on each. A Mac you can pair with answers with a mac field.

The same Mac found both ways has the same mac.id.

Steps

Everything the Mac can do is a step, like {"type": "media", "key": "next"}. A request runs a list of them in order and stops at the first that fails.

Pair with a Mac to try these.

media steps are real media-key presses, so they control whatever is playing.

Run your own

Actions

A named list of steps. Run one with {"type": "action", "id": "reload"}.

{"id": "reload", "name": "Reload", "icon": "refresh", "category": "browser",
 "steps": [{"type": "keystroke", "keys": "cmd+r"}], "custom": false}

• Built-ins cover media, the system, windows, browsers and editing.
• Save your own with POST /api/actions. They’re kept in ~/.macapad/actions.json.
• Ids use lowercase letters, numbers and dashes.
• Actions can run other actions, up to 4 deep.
• icon is a Material Symbols name, a hint for frontends.

On your Mac

HTTP API

Send your token as Authorization: Bearer <token>. Health and pairing don’t need one.

Pair with a Mac to try the GET routes.

Errors are a 4xx with {"error": {"message": "…"}}.

From a script

curl -X POST http://localhost:7317/api/run \
  -H "Authorization: Bearer $(cat ~/.macapad/token)" \
  -H "X-Macapad-Client: My script" \
  -H "Content-Type: application/json" \
  -d '{"steps":[{"type":"media","key":"playPause"}]}'

WebSocket

For a frontend that stays open. Quicker than a request per press.

1. Connect to /api/ws?token=<token>. Add &client=<name> if you name your client. (Browsers can’t set headers here.)
2. Send {"type": "run", "ref": "<anything>", "steps": [...]}. You get {"type": "result", "ref", "ok", "error", "off"?}.
3. Send {"type": "ping"} about every 25 seconds so proxies keep it open. You get {"type": "pong"}.

const ws = new WebSocket(`${base.replace(/^http/, "ws")}/api/ws?token=${token}`);
ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  if (msg.type === "result" && !msg.ok) alert(msg.error);
};
ws.onopen = () => {
  ws.send(JSON.stringify({ type: "run", ref: "skip", steps: [{ type: "media", key: "next" }] }));
};

Pair with a Mac to try it.

Live input

For controllers and trackpads: hold keys down and move the pointer in real time.

Send your whole state each time, not presses and releases, so a lost message can’t leave a key stuck:

{"n": 42, "keys": ["up", "z"], "buttons": ["left"], "dx": 3, "dy": -2, "sx": 0, "sy": 0}

• n goes up by one each time; older ones are dropped.
• keys is every key held right now: keystroke key names, the modifiers cmd shift opt ctrl fn, and media keys like volumeUp (pressed once). Held keys repeat like a real keyboard.
• buttons: mouse buttons held, left right middle.
• dx, dy move the pointer and sx, sy scroll (pixels; positive sy scrolls down), counted since the last message.

Send a message as soon as anything changes, at least every 100 ms while anything is held, and once a second otherwise. The Mac lets go of everything you hold when it hears nothing for half a second. When several clients hold keys at once, a key stays down while any of them holds it.

Over the WebSocket

Send {"type": "input", ...state}. While you’re paused you get {"type": "error", "reason": "off", "message"}.

Over UDP

Lower latency, for consoles. POST /api/input/session returns {session, udpPort, expiresAfter}. Send each state as a JSON datagram, with "s": session, to the Mac’s udpPort. Add "ack": true about once a second and the Mac answers {"type": "ok"}. A bad or expired session gets {"type": "error", "reason": "session"}: ask for a new one.

Try it: a trackpad

Pair with a Mac to try it.

Networks & tokens

Where to reach the Mac from, and which token to use.

Addresses

Macapad’s Settings choose which networks may connect and which may pair.

• Programs on the Mac itself are always allowed.
• Anything from a network that’s turned off gets 403.
• Pairing is never allowed from the internet.

Tokens

• Device tokens come from pairing. Each device has its own. Removing one in Settings cuts off only that device.
• The owner token is in ~/.macapad/token (menu bar: Copy API Token). It has full access. Use it for scripts and hand-set-up frontends.

Naming your client

With the owner token, say who’s calling, or you get 400:

X-Macapad-Client: Office display

On the WebSocket, use ?client=. Percent-encode names that aren’t plain ASCII.

Each name shows up in Settings with its own schedule and pause, so one server can drive several screens with different hours.