Adding and Managing Minions
A minion is an AI agent that works on a machine of its own. The software on that machine is Minion: it connects out to Minion Workspace (nothing on the machine needs to be reachable from the internet) and keeps itself up to date.
Ways to add a minion
Section titled “Ways to add a minion”Open Minions in the sidebar, click Add Minion and choose where the minion runs:
| Where | What happens | Good for |
|---|---|---|
| Cloud VPS | Minion Workspace sets up a VPS with Minion and manages it for you: create, restart, delete. Billed by the hour; a credit card is needed | Running around the clock without hardware of your own |
| Your machine | You install Minion on a Windows PC, a Mac or a Linux machine dedicated to the minion | Using a machine you have, or software that runs on Windows or macOS |
| Docker Container | You run the official image on a machine with Docker | A server where you already run containers |
For prices and how many minions each plan includes, see Plans.
Cloud VPS
Section titled “Cloud VPS”- Open Add Minion, choose Cloud VPS, give the minion a name and choose a size. If you haven’t registered a credit card yet, you are asked to.
- Minion Workspace creates the VPS and installs Minion on it. The minion is ready in a few minutes; you can close the dialog meanwhile.
- On the minion’s page, open the Brain tab, install Claude Code and choose what the minion uses: Minion AI, your own Anthropic API key (how), or your own Claude plan.
The VPS runs Ubuntu with a virtual display, so screen sharing works without a monitor. It opens no port to the internet.
Self-hosted minions
Section titled “Self-hosted minions”To run a minion on a machine of your own, install Minion on it:
- Windows and macOS — with an installer. Minion then shows a code; you approve it in Minion Workspace
- Linux — with one command. Started from Add Minion, the command carries a one-time token and the minion connects without approval
- Docker — with one
docker runcommand from Add Minion
Use a machine dedicated to the minion, not one you use every day: the minion’s AI works on its own on it.
Headless operation (no display)
Section titled “Headless operation (no display)”On Windows and macOS, screen sharing shows the machine’s physical screen, so it is black if no display is connected. If you plan to run the machine without a monitor, plug an HDMI dummy adapter into it: the OS treats it as a display. Linux and Docker minions use a virtual display and need nothing.
Minion statuses
Section titled “Minion statuses”| Status | Meaning |
|---|---|
| Setting up | The machine is being created, or Minion is being installed |
| Online | Connected to Minion Workspace |
| Offline | Not connected: the machine is off, Minion isn’t running, or the network is down |
| Stopped | A cloud VPS stopped because a payment failed (see below) |
Updates
Section titled “Updates”Minion updates itself on Windows, macOS, Linux and cloud VPS minions: it checks for a new version every few hours and installs it when the minion isn’t working. To update right away, use Update to version … now on the minion’s page. A Docker minion is updated by starting its container again from the new image (how).
When a payment fails (cloud VPS)
Section titled “When a payment fails (cloud VPS)”If a payment for your cloud VPS minions fails, Minion Workspace stops them the same day and keeps a snapshot of each. When the payment goes through, they are restored from the snapshot as they were. If it doesn’t within 30 days, the snapshots are deleted and can’t be restored.
Deleting a minion
Section titled “Deleting a minion”Delete a minion from the Minions page. For a cloud VPS minion, its VPS is deleted too; this can’t be undone. For a minion on your own machine or in Docker, also remove Minion from the machine: Windows, macOS, Linux, Docker.
The previous minion (Node.js version)
Section titled “The previous minion (Node.js version)”Minions set up earlier with npm (@geekbeer/minion) keep working. They can switch to Minion on the same machine, as the same minion: see Switching to the new Minion. Their own guides are kept for Windows and macOS.