Setup

From nothing to a fleet of Macs

Install once, sign in through your browser, and host. Every Mac you own joins with a single line — then drive the whole fleet from Python or watch it live in the dashboard. A few minutes, start to finish.

Install the CLI

One command on any Mac — it pulls a self-contained runtime, so there’s nothing to install first. Already have Python? A plain pip install grabs the same package.

your Mac — zsh

# pulls a self-contained runtime — nothing to install first
$curl -fsSL herds.run/install | sh
✓ installed herds 0.1

Sign in from your browser

Run herds auth. It opens your browser with a short code — confirm it matches, sign in, and the token syncs straight back to this Mac. No copy-pasting secrets.

your Mac — zsh

$herds auth
# opens herds.run/activate — approve the code shown
✓ approved in browser
✓ signed in as you@team.com

On a headless box? herds auth --no-browser prints the link + code, or herds auth --token hx_… signs in directly.

Go live

Host turns this Mac into your control plane and opens a public, branded link through the relay — no inbound ports, no port-forwarding. Your browser opens already signed in.

your main Mac — zsh

$herds host
✓ control plane up · dashboard built
✓ live at you.herds.run
# opening you.herds.run/?token=… — you're signed in

Add more Macs

Any other Mac you own joins the same fleet. Brand-new machine or one that already has Herds — pick your path. Repeat for as many as you like.

on the new Mac — zsh

# one line: installs Herds, then joins your fleet
$curl …/install | sh -s -- you.herds.run hx_…
✓ Mac mini · M2 Pro joined the fleet

Drive it — Python or the web

Target the idlest matching Mac by tag, run anything, and expose a port as a public URL. Or just watch it all live in the dashboard the relay serves.

agent.py

import herds
mac = herds.mac(tag="xcode") # idlest match
mac.run("xcodebuild -scheme App")
url = mac.expose(3000) # → public URL

Open the dashboard Read the SDK docs

Keep it running (optional)

Make a Mac a permanent node: a login agent restarts herds host on boot and after a crash, so the fleet stays up on its own.

zsh

$herds install
✓ installed login agent · ai.spawnlabs.herds
✓ host will restart on login & after crashes

Good to know

One Mac is a whole fleet on its own

Each machine isn’t just one runtime — you can carve a single Mac mini into dozens of isolated, localized sandboxes, each with its own HOME, filesystem, and ports, all running in parallel and torn down clean. Drive the machine directly, or fan work out across the grid.

agent.py

with herds.mac("mac-mini").sandbox(image="xcode:26") as sbx:
sbx.exec("xcodebuild -scheme App archive")
url = sbx.expose(3000) # its own public URL

Connect your first Mac

Every Mac becomes an API. Your machines, your infra — live with one command.

Start free Docs