Running a minion in Docker
A minion can run as a Docker container, from the official image ghcr.io/geek-beer/minion-agent. The container connects out to Minion Workspace (you don’t publish any port) and works on a virtual display inside the container.
What you need
Section titled “What you need”- Docker on a machine that stays on — a server, or a PC with Docker Desktop. The image is for x86_64 and arm64
- A Minion Workspace account
Start the minion
Section titled “Start the minion”Open Minions in the sidebar, click Add Minion, choose Docker Container and create the minion. Minion Workspace shows the command to run, with a one-time enrollment token and your time zone:
docker run -d \ --name minion-1a2b3c4d \ --restart unless-stopped \ --pull always \ -e TZ=Asia/Tokyo \ -e MINION_ENROLL_TOKEN=mwe_… \ -v minion-1a2b3c4d-data:/var/lib/minion \ -v minion-1a2b3c4d-home:/home/minion \ ghcr.io/geek-beer/minion-agent:latestRun it on the machine. The minion connects within a few seconds; the page shows it when it does. The token works once and only for 30 minutes: if it expires, add the minion again.
The minion keeps its data in the two volumes: …-data is Minion Agent’s (including the key the machine connects with) and …-home is the home folder of minion, the user the AI works as. Keep both: the minion needs them to come back as itself.
Then open the Brain tab on the minion’s page, install Claude Code and choose what the minion uses: Minion AI, your own Anthropic API key (how), or your own Claude plan.
Updating
Section titled “Updating”The container doesn’t update itself. To move to a new version, pull the image and start the container again with the same name and volumes — without the token, since the minion is already registered:
docker pull ghcr.io/geek-beer/minion-agent:latestdocker rm -f minion-1a2b3c4ddocker run -d \ --name minion-1a2b3c4d \ --restart unless-stopped \ -e TZ=Asia/Tokyo \ -v minion-1a2b3c4d-data:/var/lib/minion \ -v minion-1a2b3c4d-home:/home/minion \ ghcr.io/geek-beer/minion-agent:latestDay-to-day
Section titled “Day-to-day”| What | How |
|---|---|
| Is Minion running and connected? | docker exec minion-1a2b3c4d minion status |
| Logs | docker logs minion-1a2b3c4d |
| Restart | Restart Agent on the minion’s page, or docker restart minion-1a2b3c4d |
Removing
Section titled “Removing”docker rm -f minion-1a2b3c4ddocker volume rm minion-1a2b3c4d-data minion-1a2b3c4d-homeRemoving the volumes deletes what the minion kept. Then delete the minion on the Minions page.
Troubleshooting
Section titled “Troubleshooting”The minion doesn’t connect
Section titled “The minion doesn’t connect”Run docker logs on the container. If the token had expired (or was already used), add the minion again and use the new command. If you started the container without a token, docker exec <name> minion status shows a code and a link: open the link while signed in to Minion Workspace and approve.