Skip to content

Switching to the new Minion

A minion you set up earlier with npm (@geekbeer/minion, the Node.js version) can switch to the new Minion on the same machine, as the same minion. Its name, the workspace it belongs to and its project memberships, the tickets assigned to it and its AI usage limits stay as they are. The minion’s data moves on the machine itself and never passes through Minion Workspace.

The switch takes effect when the minion’s owner approves it in Minion Workspace.

DataHow it moves
MemoriesTo every workspace the minion is in. A project’s memories go to that project’s workspace
Daily logsDay by day, to their workspace
To-dosTo-dos finished more than 30 days ago are not moved
RoutinesA name that does not fit the new rule (lowercase letters, digits and -) is changed
Chat historyMoved so you can read it. The minion does not continue those conversations
FilesThe minion’s files folder
Minion AppsThe apps’ data, and the code of apps the minion’s AI made
Permissions and reflection timeThe deny rules you added, and the reflection time

Routines, to-dos and chats that belonged to no workspace go to the workspace you choose when you start the switch.

  • Secrets — their values do not move. The switch report lists their names so you can enter them again
  • Variables — the new Minion has no minion variables. The report lists their names and values so you can add them as workspace variables
  • Run history, and local skills that Minion Workspace does not have
  • Your own Claude sign-in — when the previous minion ran as the user minion (as the macOS guide set it up), that user is taken over and the sign-in stays. Otherwise, sign in again from the Brain tab
  • Settings for AIs other than Claude (Gemini, Codex)

Anything not moved is listed in the switch report with the reason. The previous minion’s data is kept on the machine for 30 days (without the secrets’ values and the API token).

  • Work the minion is running stops during the switch
  • Only the minion’s owner can start the switch and approve it. If you use two-factor authentication, you are asked for a recent code (from the last 10 minutes by default; the workspace can change this)
  • A previous minion connected to another Minion Workspace (a different URL) cannot be switched

On the minion’s detail page, the Overview tab shows Switch to the new Minion. Choose the kind of machine to see its steps.

Press Start switching. Minion Workspace updates the previous minion to the last Node.js version, and that update installs the new Minion and takes the minion over. It takes about 10 minutes and needs no approval. If it does not work out, the previous minion keeps running and the detail page shows why. The VPS stays the same, so the charges do not change.

  1. Install the new Minion from Download Minion (Windows, macOS)
  2. When the installer finds the previous minion, it asks whether to take it over. Choose OK on Windows and Continue on macOS. If the installation fails, the previous minion keeps running as it was
  3. The Minion window shows an approval code and says to approve it as a takeover. Open the link and press Approve and take over

A silent installation (msiexec /qn) cannot ask, so add TAKEOVER_NODE=1 to take the minion over. Without it, the installation stops on a PC that has the previous minion.

The worker’s user on Windows and macOS:

  • If the previous minion ran as the user minion (as the macOS guide set it up) — that user is taken over as the worker. Its password, automatic sign-in and your own Claude sign-in stay. If it is in an administrators’ group, remove it from the group before installing
  • Otherwise (it ran as your own account) — a new minion user is created and the files folder is copied there. Set the minion password and sign in as the setup guide says
  1. Choose Linux and press Start switching to see a command
  2. Run that command on the previous minion’s machine within 30 minutes (it needs sudo)
Terminal window
curl -fsSL https://minionworkspace.com/setup/minion.sh | sudo sh -s -- --take-over-node --enroll-token mwe_…

The command contains this minion’s enrollment token. Do not show it to anyone. If the installation fails, the previous minion keeps running as it was.

  1. Choose Docker container, enter the current container’s name and press Start switching to see the commands
  2. Run them within 30 minutes on the machine that has the previous container. They copy the data out of the previous container (./minion-takeover), stop it and start the new container
  3. Once the switch is done, you can delete the previous container and ./minion-takeover

The detail page shows the Switch report.

  1. Check what moved and what did not
  2. Enter the Secrets to enter again on the Env tab. In the new Minion, secrets belong to a workspace, and a run gets only the ones its skill declares
  3. Add the variables as workspace variables
  4. On the Brain tab, check that the AI is connected. Minion AI and your own API key are reconnected during the switch. Sign in again to your own Claude plan unless the user was taken over
  5. What is Left on the machine (Node.js, Homebrew tools, TightVNC and so on that the previous minion installed) can be removed if nothing else uses it

Minion Workspace reinstalls the Minion Apps after the switch.

The approval page says the minion’s owner needs to approve it

Section titled “The approval page says the minion’s owner needs to approve it”

Only the minion’s owner can approve a takeover. Open the page again with the owner’s account.

The previous minion keeps running as it was. Common causes:

  • The previous minion is connected to another Minion Workspace (a different URL)
  • The user minion to take over is in an administrators’ group
  • On macOS, the previous minion is set up for more than one user (keep one and uninstall the others)

The reason is in the installer’s message on Windows, and in the minion lines of /var/log/install.log on macOS.

The Linux command stops, saying an older Minion is installed

Section titled “The Linux command stops, saying an older Minion is installed”

A command without --take-over-node stops when it finds the previous minion. Use the command that Switch to the new Minion shows on the minion’s detail page.

To start fresh with a new minion instead, uninstall the previous minion first (Windows, macOS; on Linux, sudo minion-cli uninstall and then sudo npm uninstall -g @geekbeer/minion), install Minion and approve it as a new minion. In that case the previous minion’s secrets, variables, memories, daily logs, to-dos, routines, run history, chat history, files and Minion Apps data do not move. Copy what you need to notes or the drive before uninstalling.