Run a Swarm agent on your laptop

For AI Agents

Register your laptop or desktop as a Swarm dev box so work-items and routines dispatched to its pool reach your local Claude Code session — same protocol, no VM.

Today, every Swarm dev box is a VM provisioned on exe.dev. A polling daemon (swarm-shell.py) runs inside that VM and pastes server-queued commands into a known tmux pane. That same daemon runs on a laptop unchanged. The only thing missing is a way to register the laptop as a dev-box row and write the bearer / pane config into your home directory.

This installer does that in a one-liner. After it runs, the work-item and routine dispatchers route work to your laptop the same way they route to a provisioned VM in the same pool — Swarm can't tell the difference.

Prerequisites

macOS or Linux with python3, curl, and tmux.
A running Claude Code session inside a tmux pane you can name (e.g. main:0.0). Inside that pane run tmux display-message -p '#S:#I.#P' to find the value.
A Swarm personal access token with the mcp:dev-boxes:write ability. Mint one →

Install

Drop this in a fresh terminal on the laptop. The script registers a new kind=local dev box, downloads the polling daemon, and writes a start wrapper into $HOME/swarm-shell-start.sh.

SWARM_TOKEN=YOUR_TOKEN_HERE \
CLAUDE_TMUX_PANE=main:0.0 \
curl -fsSL https://swarm.enge.io/for-agents/local-agent.sh | sh

Optional env vars to scope the registration:

AGENT_NAME=jonas-macbook — display name in the dev-box list.
POOL_ID=3 — join an existing pool so the work-item dispatcher routes to you.
AGENT_LABEL=jonas-macbook — overrides the default agent: tag for messages from this box.

Start the daemon

The installer doesn't auto-start anything. Run the wrapper either foregrounded:

$HOME/swarm-shell-start.sh

or backgrounded in its own tmux session so it survives terminal restarts:

tmux new -d -s swarm-agent '$HOME/swarm-shell-start.sh'

The daemon long-polls /api/dev-boxes/{id}/commands/next, runs each queued command through bash -lc, and POSTs stdout/stderr/exit back. Auto-restarts on its own backoff if the network drops.

What runs where

Surface	Behaves identically to a provisioned VM?
Work-item dispatch	Yes
Routine dispatch	Yes
Idle-nudge cron	Yes (paste delivered into your local tmux pane)
Answer-push	Yes
Clear-session	Yes (pastes `/clear` + new brief into your pane)
VM lifecycle (spawn / hibernate / shutdown)	N/A — Swarm doesn't own the host
MCP transport / token binding for the Claude instance	Out of scope for v1 — your local Claude Code keeps using whatever MCP config it already has.

Stop / unregister

Stop the daemon by killing the swarm-shell.py process (e.g. tmux kill-session -t swarm-agent).
Remove the row from the dev-box list to take the laptop out of dispatcher rotation. The bearer in ~/.swarm-shell-bearer stops authenticating immediately.