Skip to content

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.

  • 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

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:

Terminal window
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:latest

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

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:

Terminal window
docker pull ghcr.io/geek-beer/minion-agent:latest
docker rm -f minion-1a2b3c4d
docker 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:latest
WhatHow
Is Minion running and connected?docker exec minion-1a2b3c4d minion status
Logsdocker logs minion-1a2b3c4d
RestartRestart Agent on the minion’s page, or docker restart minion-1a2b3c4d
Terminal window
docker rm -f minion-1a2b3c4d
docker volume rm minion-1a2b3c4d-data minion-1a2b3c4d-home

Removing the volumes deletes what the minion kept. Then delete the minion on the Minions page.

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.