# Murmur: more silicon for the AI on this Mac

Hand Murmur a NumPy script and a deadline; it finds the fewest of the human's own Macs, this one included, that meet it. You, the AI agent on this Mac, call the `murmur_run_script` tool and get the answer plus a verdict on whether the deadline was met. Install first (below); the tool exists only after setup.

- **When to use it:** a job that would be slow here, or one with a deadline from the user.
- **Where it runs:** only on Macs joined to the human's own Murmur server. The script, inputs and results never go to Murmur or any third-party host; only licence and usage-count metadata do.
- **What the human does:** signs in, starts the trial on a checkout page (2 weeks, 4 devices), and copies a join folder to each extra Mac. You do everything else.

## Install Murmur on this Mac (instructions for an AI agent)

You are installing Murmur for the human at this Mac. You run every command yourself; the human only authenticates.

**First, check which kind of install this is.** If the folder `~/murmur-join` exists and `~/.murmur/server` does not, another Mac on this network already runs the Murmur server and this Mac joins it as a worker: skip steps 2-5 and follow "On device 2 (the new worker)" under "Add your other idle devices" at the end. Never run `murmur setup` on a Mac that has `~/murmur-join`. Otherwise this Mac is the first one: follow steps 1-6.

1. Run the installer: `curl -fsSL https://cdn.murmurcomputing.ai/install.sh | sh`
   The last stdout line is a JSON verdict. `"ok":true` means continue; `"ok":false` gives `error.code`, `message`, `hint` and `retryable`.
2. Set up the local server: `~/.murmur/bin/murmur setup`. Setup installs a background worker on this Mac that starts at login, so tell the human that before you run it. Setup downloads the licensed planner itself after sign-in; never ask the human for the licence key.
3. Every `murmur setup` call ends with a one-line JSON verdict. Read it; do not guess.
   - Exit 0, `ok:true`: run each command in `next` exactly as given (it registers the Murmur MCP with Claude Code). Then `claude mcp list` (use the same absolute claude path) must show `murmur` as Connected. Your current session cannot see the new murmur tools yet, so relay the verdict's `say`, then stop and run nothing else until you are resumed. Ask the human, in these words: "Murmur is set up. Please type /exit, then run `claude --continue` in this same folder; I'll pick up where we left off." When you are resumed, confirm the murmur tools are available to you (if not, do not fall back to the CLI), then go to step 5.
   - Exit 10, `needs_human`: show the human `needs_human.url` and `needs_human.user_code` and repeat `needs_human.say`. Wait for them to say they finished, then run the command in `needs_human.then` (normally `~/.murmur/bin/murmur setup --complete`).
   - Any other error: follow its `hint` (retry if `retryable` is true), then re-run the same step. Setup can be re-run safely.
4. If a verdict lists `os_prompts`, or you are about to do something that makes macOS show a dialog (background items, firewall, network access), tell the human first what will appear and what to click.
5. Run the first job with the Murmur MCP tool `murmur_run_script`, not the CLI: write the script to an absolute path, put any .npy files it np.load()s next to it, call `murmur_run_script` with `script_path` and `deadline: "2m"`, and report `outputs` and `deadline.verdict`. Never run the first job with the CLI. If the murmur tools are not available to you, stop and ask the human again to type /exit and run `claude --continue`, then retry.
6. Never ask the human to run commands, use sudo, or install developer tools. The only things the human does are sign-ins and payment pages.

## Add your other idle devices (other Macs on the same network)

Do this after step 5 succeeds, when the human wants another Mac to work for this server. Only one Mac runs the server; every other Mac is a worker. Two agents take part: the one on this Mac (device 1, the server) and the one on the other Mac (device 2). Each script ends with a one-line JSON verdict on stdout; read it the same way as in step 3.

On device 1 (the server):
1. Make the join kit: `curl -fsSL https://cdn.murmurcomputing.ai/join/make-join-kit.sh | sh -s -- <device-2-name>`
   It mints a key for the new device (`murmur server key --label team:<device-2-name>`), finds this Mac's LAN IP, and writes `~/murmur-join` (0700) with `ca.crt`, `team-key.txt`, `join.txt` and `join.sh`, all 0600. The key is never printed; never put it in a command line or in chat.
2. Tell the human the verdict's `say`: "Copy the folder ~/murmur-join to the other Mac's home folder (AirDrop or a USB stick), then open Claude Code there and point it at START-HERE. Afterwards delete ~/murmur-join on this Mac." (Murmur does not have a one-approve join yet, so this copy is the one manual step.)

On device 2 (the new worker):
1. Tell the human first: "This installs a background worker that starts at login. macOS will ask to let Murmur find devices on your local network. Click Allow."
2. Run `sh ~/murmur-join/join.sh`. Do NOT run install.sh or `murmur setup` yourself: join.sh installs the CLI if it is missing, refuses if this Mac already runs a server, logs in with the key over stdin, installs the worker, and deletes `~/murmur-join/team-key.txt` even if it fails. Report `data.worker_id` from its verdict. If it fails, follow the verdict's `hint`; a re-run needs a fresh kit from device 1.

Back on device 1: `murmur_fleet` must now list one more worker. Report both worker ids to the human.