Installation

Monoceros runs on macOS, Linux and Windows. Everywhere you need Docker, the engine that runs your workbenches. On macOS and Linux you also need Node.js 20+, the runtime the monoceros CLI is built on. On Windows the installer provides Node inside its managed WSL distro, so you don’t install it yourself.

The install script checks both and, if either is missing, prints the exact command for your system - so you can often just run it and let it guide you. The per-OS steps below are for when you’d rather prepare first, or something needs a hand.

macOS

1. Install Docker Desktop (or a drop-in such as Colima or OrbStack) and start it.

2. Install Node.js 20+ 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 native 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

2. Install Node.js 20+ and npm. On Debian/Ubuntu, via NodeSource - the distro’s own nodejs package usually lags well behind:

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

   On other systems (Fedora/RHEL, or a version manager like fnm / nvm), see nodejs.org/en/download.

3. Install Monoceros:

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

Tip

No newgrp docker, no logout, no reboot. Monoceros detects the “user is in the docker group but this shell doesn’t know yet” state and handles it internally.

Note

sudo -v caches your sudo password so that, in a pasted block, the next command isn’t swallowed by a delayed password prompt. Typing the commands one by one, it is redundant.

Windows

On Windows, the installer sets up its own managed WSL distro for Monoceros - you never install or configure a Linux distro by hand. All you provide is Docker:

1. Install Docker Desktop and start it:

   winget install Docker.DockerDesktop

2. Install Monoceros in PowerShell. It creates the managed monoceros WSL distro, enables Docker Desktop’s WSL integration for it, adds the monoceros command, and prompts for admin once:

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

Note

You never touch WSL directly - no wsl --install Ubuntu, no integration toggle. The installer needs WSL 2 available (built into Windows 11) and manages its own distro, reusing it (and preserving your config) on re-runs.

Next

With Monoceros installed, head to Your first workbench to build one and put an agent to work.

When you want it gone again, Uninstall reverses all of this in one command.