Skip to content

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.

Open Minions in the sidebar, click Add Minion and choose where the minion runs:

WhereWhat happensGood for
Cloud VPSMinion Workspace sets up a VPS with Minion and manages it for you: create, restart, delete. Billed by the hour; a credit card is neededRunning around the clock without hardware of your own
Your machineYou install Minion on a Windows PC, a Mac or a Linux machine dedicated to the minionUsing a machine you have, or software that runs on Windows or macOS
Docker ContainerYou run the official image on a machine with DockerA server where you already run containers

For prices and how many minions each plan includes, see Plans.

  1. 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.
  2. Minion Workspace creates the VPS and installs Minion on it. The minion is ready in a few minutes; you can close the dialog meanwhile.
  3. 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.

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 run command 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.

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.

StatusMeaning
Setting upThe machine is being created, or Minion is being installed
OnlineConnected to Minion Workspace
OfflineNot connected: the machine is off, Minion isn’t running, or the network is down
StoppedA cloud VPS stopped because a payment failed (see below)

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).

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.

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.

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.