Installation

Monoceros runs on macOS, Linux and Windows. On every system you need Docker, which runs your workbenches. On macOS and Linux you also need Node.js 20 or newer, because the monoceros CLI runs on it. On Windows the installer brings its own Node, so you don’t install it yourself.

The install script checks for both. If one is missing, it prints the exact command for your system. So you can often just run the script and follow what it says. The steps below are for when you want to prepare your machine first.

macOS

1. Install Docker Desktop and start it. Colima and OrbStack work too.

   Docker Desktop includes Docker Compose and Buildx. With Colima and the Homebrew Docker CLI, you install both yourself and link them into ~/.docker/cli-plugins. The install script checks this and prints the commands for your machine.

2. Install Node.js 20 or newer if you don’t have it, for example with Homebrew:

   brew install node

3. Install Monoceros:

   curl -fsSL https://raw.githubusercontent.com/getmonoceros/workbench/main/installer/install.sh | bash

Linux

On a Linux desktop, Monoceros uses Docker Engine in rootful mode, not Docker Desktop.

1. Install Docker Engine and add yourself to the docker group:

   sudo -v
   curl -fsSL https://get.docker.com | sudo sh
   sudo usermod -aG docker $USER

   sudo -v asks for your password up front. Without it, a password prompt in the middle of a pasted block can swallow the next command.

2. Install Node.js 20 or newer and npm. On Debian and Ubuntu, use NodeSource. The nodejs package of the distribution is usually too old:

   curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
   sudo apt install -y nodejs npm

   For other systems, or a version manager like fnm or nvm, see nodejs.org/en/download.

3. Install Monoceros:

   curl -fsSL https://raw.githubusercontent.com/getmonoceros/workbench/main/installer/install.sh | bash

Tip

You don’t need newgrp docker, a logout or a reboot after step 1. Monoceros notices when your shell does not know the new group yet, and handles it.

Windows

The installer sets up its own WSL distro for Monoceros. You never install or configure a Linux distro yourself. You only need Docker:

1. Install Docker Desktop and start it:

   winget install Docker.DockerDesktop

2. Install Monoceros in PowerShell. The script creates the monoceros WSL distro, turns on Docker Desktop’s WSL integration for it and adds the monoceros command. It asks for admin rights once:

   irm https://raw.githubusercontent.com/getmonoceros/workbench/main/installer/install.ps1 | iex

Note

The installer needs WSL 2, which Windows 11 includes. When you run it again, it reuses its distro and keeps your configs.

Update

To update Monoceros, run the install command for your system again.

Do you still have a monoceros-config.yml from an older version? The install script moves its settings into monoceros-config.env and tells you what moved. See Workbench configuration.

Next

Monoceros is installed. Now build your first workbench and put an agent to work.

To remove Monoceros again, see Uninstall.