Setting up a Linux minion
Install Minion on a Linux machine with one command and the machine works as your minion. Minion runs as systemd services, connects out to Minion Workspace (you don’t open any port) and updates itself. The minion works on a virtual display, so the machine needs no monitor and nobody has to sign in.
What you need
Section titled “What you need”- Linux with systemd, on x86_64 or arm64. Ubuntu (22.04 or later) or Debian (12 or later) is recommended: the command installs packages with
apt(distributions withdnfalso work) and checks the signature with OpenSSL 3 - A user who can become root (
sudo) - A Minion Workspace account
Install
Section titled “Install”There are two ways. Both install the packages Minion needs (a virtual display, the libraries the browser needs, Japanese fonts and so on), check the download’s signature, and start Minion Agent.
From “Add Minion” (no approval needed)
Section titled “From “Add Minion” (no approval needed)”Open Minions in the sidebar, click Add Minion, choose Your machine, then Linux, and create the minion. Minion Workspace shows a command with a one-time enrollment token. Run it on the machine:
curl -fsSL https://minionworkspace.com/setup/minion.sh | sudo sh -s -- --enroll-token mwe_…The minion connects as soon as Minion is installed; the page shows it when it does. The token works once and only for 30 minutes: if it expires, add the minion again.
Without a token (approve a code)
Section titled “Without a token (approve a code)”curl -fsSL https://minionworkspace.com/setup/minion.sh | sudo shWhen it finishes, the terminal shows a code and a link. Open the link while signed in to Minion Workspace, give the minion a name, choose the workspace it belongs to (one where you are the owner or an admin) and click Approve. minion status shows the code and the link again. The code is valid for 10 minutes; if it expires, minion status shows a new one.
Set up the AI
Section titled “Set up the AI”On the minion’s page in Minion Workspace, open the Brain tab, install Claude Code, then choose what the minion uses: Minion AI, your own Anthropic API key (how), or your own Claude plan (sign in from the tab; it opens the minion’s terminal in Minion Workspace).
Then check on the minion’s page that the minion is online, that the Terminal opens a shell as minion and that Screen sharing shows its desktop, and send it a message from the chat.
What the install sets up
Section titled “What the install sets up”- Two users:
minion-agent(Minion Agent) andminion(the user the AI works as; it has no password and can’t log in) - The services
minion-agent(Minion Agent),minion-worker(the AI’s side),minion-displayandminion-window(the virtual display, 1280×800) andminion-updater - The
minioncommand in/usr/local/bin
Updates
Section titled “Updates”Minion updates itself: 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, or run sudo minion update --now. minion update shows the updater’s state.
Day-to-day
Section titled “Day-to-day”| What | How |
|---|---|
| Is Minion running and connected? | minion status |
| Logs | journalctl -u minion-agent (the AI’s side: journalctl -u minion-worker) |
| Restart | Restart Agent on the minion’s page, or sudo systemctl restart minion-agent |
Uninstalling
Section titled “Uninstalling”sudo minion uninstallThe data Minion kept on the machine (both users included) is removed too. Then delete the minion on the Minions page if you no longer need it.
Reinstalling
Section titled “Reinstalling”If you install Minion again on the same machine, you can connect it back to the same minion. What Minion Workspace keeps (its name, its workspace and project memberships, tickets assigned to it and so on) carries on. The data on the machine itself (memories, routines, to-dos and so on) was removed when you uninstalled.
- In Minion Workspace, open the minion’s Overview tab and click Reset pairing
- Install Minion again the way “Without a token (approve a code)” describes. On the approval page, under How to connect, choose Reattach to an existing minion and pick the minion
Troubleshooting
Section titled “Troubleshooting”It says an older version of Minion is installed
Section titled “It says an older version of Minion is installed”The previous minion (installed with npm, the Node.js version) is on the machine. To switch it to the new Minion as the same minion, use the command that Switch to the new Minion shows on the minion’s detail page (Switching to the new Minion). To start fresh with a new minion instead, remove the previous one and run the command again:
sudo minion-cli uninstallsudo npm uninstall -g @geekbeer/minionIt says the release list’s signature does not check out
Section titled “It says the release list’s signature does not check out”What was downloaded isn’t what Minion Workspace published, so nothing was installed. Run the command again later; if it keeps failing, please contact us.
The minion stays offline
Section titled “The minion stays offline”Run minion status. If it shows waiting for approval with a code and a link, open the link and approve. If Minion Agent isn’t running, look at journalctl -u minion-agent.