Skip to content

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.

  • 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 with dnf also work) and checks the signature with OpenSSL 3
  • A user who can become root (sudo)
  • A Minion Workspace account

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:

Terminal window
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.

Terminal window
curl -fsSL https://minionworkspace.com/setup/minion.sh | sudo sh

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

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.

  • Two users: minion-agent (Minion Agent) and minion (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-display and minion-window (the virtual display, 1280×800) and minion-updater
  • The minion command in /usr/local/bin

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.

WhatHow
Is Minion running and connected?minion status
Logsjournalctl -u minion-agent (the AI’s side: journalctl -u minion-worker)
RestartRestart Agent on the minion’s page, or sudo systemctl restart minion-agent
Terminal window
sudo minion uninstall

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

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.

  1. In Minion Workspace, open the minion’s Overview tab and click Reset pairing
  2. 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

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:

Terminal window
sudo minion-cli uninstall
sudo npm uninstall -g @geekbeer/minion

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

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.