Choose where an agent runs
When you start an agent, the Runs on chip in the message box picks where it runs: Cloud, or one of your machines that’s online. An agent stays on the machine it started on. Only your own agents run on your machines. A teammate’s agent can still send terminal commands to your Mac, as Terminal commands explains.This Mac
In the Mac app, turn on Run agents on this Mac to run agents on the Mac you’re using. Agents won’t start until you allow Vespin in System Settings › General › Login Items. Turning it off stops any agent running there.Add a machine
To add a Linux server, or a Mac that doesn’t have the app, run this on it as the user who should run the agents. Don’t usesudo.
- Linux on x64 or arm64 with systemd, or WSL2 on Windows
- An Apple silicon Mac on macOS 13.5 or later
git
Set up a machine with a coding agent
You can ask a coding agent like Claude Code or Codex to set up a machine it can reach. These steps are written for the agent:-
Run
curl -fsSL https://vespin.dev/install.sh | shon the machine as the user who will run agents, withoutsudo. Don’t install the Mac app, and don’t installvespin-hostany other way. -
The script waits up to 10 minutes for approval. If your shell tool only shows output once a command finishes, or times out sooner, run the script in the background and read its log:
- Give the person the link and code the script prints, and wait for them to approve it.
-
Wait for
Ready: this machine takes agents.You can check at any time with~/.local/bin/vespin-host status. - Make sure the same user is signed in to Claude Code or Codex, and to GitHub. If not, ask the person to sign in.
✗, its message explains what’s missing and how to fix it. Sometimes that’s a command the person needs to run with sudo. Fix the problem and run the script again.
How agents work on a machine
Each agent gets its own folder in~/.vespin/agents with a worktree of the repository. It runs as the machine’s user and can reach anything that user can. Claude Code and Codex use the logins on the machine, and git and gh use that user’s GitHub sign-in and SSH keys. Agents still follow their permission mode.
Agents on a machine don’t get your workspace’s cloud environment variables, and their dev servers run on the machine itself rather than through Ports. If a machine goes offline, its agents can’t take messages until it’s back, and any unpushed changes stay on it.
Terminal commands
Agents in the cloud or on another machine can run shell commands on your Mac with therun_on_mac tool. Commands run in your login shell, from your home folder. Terminal commands sets whether Vespin asks first:
- Ask every time (default): you approve each command.
- Always allow: commands from your agents run without asking.
- Never: no commands run.
Remove a machine
Choose Remove from a machine’s ⋯ menu. Vespin stops sending it agents and uninstalls itself from the machine. Agent folders stay in~/.vespin/agents, and tasks and transcripts stay in Vespin. If the machine is offline, it uninstalls the next time it comes online.
You can also run ~/.local/bin/vespin-host uninstall on the machine. That deletes the agent folders too, unless you add --keep-agents.
Logs
- Linux:
journalctl --user -u vespin-host - Mac:
~/Library/Logs/Vespin Host/vespin-host.log