# Swarm for a person on a Mac (for AIs)

For AIs helping a person whose computer is a Mac. **Swarm does not run on macOS yet.** The installer needs Ubuntu 24.04 on x86_64: it refuses any other architecture (`uname -m` must be `x86_64`), and its release build is Linux amd64 only. Tell the person this plainly, then set Swarm up on a Linux server they own and drive it from the Mac. They keep talking to you on the Mac; Swarm's workers run on the server.

Do not try, and do not suggest:

- Homebrew, Docker Desktop or anything else that runs Swarm on macOS itself.
- An Ubuntu VM on an Apple silicon Mac (M1 and later): the VM is arm64 and the installer stops. Emulating x86_64 on Apple silicon is too slow to be worth it.

On an Intel Mac, an Ubuntu 24.04 x86_64 VM on the Mac passes the installer's checks, but the Swarm team has not tested it. Offer it only if the person asks for something local; the server below is the recommended route.

You run every command. The person only creates the server, adds their SSH key to it, and signs in where you tell them. Never ask for a password or a key in chat.

## 1. The server

Any Ubuntu 24.04 x86_64 machine the person controls:

- a VPS or a cloud VM in their own account (any provider; pick Ubuntu 24.04 LTS, x86_64 / amd64, not ARM), or
- a Linux PC at home that stays on.

Suggest at least 2 vCPUs, 4 GB of memory and 40 GB of disk (more if the person wants environments, which build container images there).

Access is SSH with a key from the Mac:

1. On the Mac, check for an ed25519 SSH key in the person's SSH folder. If there is none, make one with `ssh-keygen -t ed25519` (the default file; a passphrase only if the person wants one, and they type it, not you).
2. Show the person the public key (the `.pub` file of that key, safe to show) and tell them to paste it into the provider's SSH key field when they create the server. Ask for the server's address and login user (often `ubuntu` or `root`).
3. Check it: `ssh -o StrictHostKeyChecking=accept-new USER@HOST 'cat /etc/os-release | head -3; uname -m; sudo -n true && echo sudo-ok'`. You need Ubuntu 24.04, `x86_64` and `sudo-ok`. Logging in as root works too; then the install runs for that user, and you should create a normal user for the person first (`adduser`, `usermod -aG sudo`), add their SSH key to that user and use that user from here on.

## 2. Install Swarm on the server, from the Mac

Install with Tailscale at the same time, so the Mac can reach Swarm privately:

    ssh -t USER@HOST 'curl -fsSL https://swarmagent.dev/install | sudo bash -s -- --tailnet'

- It takes a few minutes. It prints a Tailscale login link: give it to the person at once. They need a Tailscale account with MagicDNS and HTTPS certificates on (admin console, DNS page).
- Without Tailscale, run the plain install (`... | sudo bash`) and use the SSH tunnel in step 3B.

## 3. Connect the Mac to Swarm

### A. Over Tailscale (recommended)

1. The person installs the Tailscale app on the Mac and signs in to the same tailnet.
2. `ssh USER@HOST 'sudo bash /var/lib/swarm-headless/install.sh status'` shows Swarm's tailnet MCP, `https://NAME.TAILNET.ts.net:8444/mcp`.
3. Follow "Who may use it" and "On the other device" in https://swarmagent.dev/ai/connect-tailscale.md (a tailnet policy, or the person's AI key copied privately).

### B. Over SSH, no other account

A tunnel brings the server's MCP and setup page to the Mac's loopback:

    ssh -N -L 7783:127.0.0.1:7783 -L 8443:127.0.0.1:8443 USER@HOST

Keep it running (in the background, or as a launchd agent if the person wants it permanent). Copy the AI key privately, never through chat:

    (umask 077; mkdir -p ~/.config/swarm && ssh USER@HOST 'cat ~/.config/swarm/ai-key' > ~/.config/swarm/ai-key)

Then connect exactly as on the machine itself (https://swarmagent.dev/llms.txt, step 3): MCP at `127.0.0.1:7783/mcp` with `Authorization: Bearer <contents of ~/.config/swarm/ai-key>`. The setup page is at `127.0.0.1:8443` in the Mac's browser while the tunnel runs; that is where the person types a model API key, if they use one.

## 4. The person's work lives on the server

Workers work on folders on the server, not on the Mac.

- Put the work there: `ssh USER@HOST 'git clone REPO ~/work/NAME'`. If a repository needs a sign-in to clone, the server needs its own access (a deploy key or `gh auth login` on the server, done by the person); never copy the person's Mac credentials to it.
- Create the project from those server paths (`swarm_create_project`).
- Getting results back to the Mac: after you deliver a job (a merge into the server's folder), pull it on the Mac: `git -C ~/path/on/mac pull USER@HOST:work/NAME BRANCH`, or set up publishing so delivery opens a pull request.

## 5. Then

Continue with https://swarmagent.dev/llms.txt from step 4 (connect a model provider). Everything else is the same; the machine is just somewhere else. To add more machines later: https://swarmagent.dev/ai/fleet.md.