Performance

Monoceros builds the same workbench from the same yml on every machine - but Docker itself runs differently per operating system, and that difference is where speed is won or lost. The good news: on each OS there are only one or two settings worth knowing, and the defaults are mostly right.

Linux

Nothing to tune. Containers run directly on the host kernel with no virtual machine in between, so file access and builds run at native speed. This is the fastest case by default.

macOS

Docker Desktop runs your containers inside a lightweight Linux VM, so files shared between the host and the container cross a VM boundary. How fast that boundary is comes down to three settings, all on one panel. In Docker Desktop, open Settings then General and scroll to Virtual Machine Options:

Docker Desktop Settings, General tab: the Virtual Machine Options panel with the VMM choice (1), the Rosetta checkbox (2), and the file sharing implementation (3)

(1) Virtual Machine Manager (VMM). This is the hypervisor running the Linux VM, and it is the biggest lever. You get two modern choices, and both support the fast file sharing in (3):

Apple Virtualization framework - the stable default, and the one Rosetta in (2) needs.
Docker VMM (beta) - Docker’s own hypervisor, tuned for Docker workloads. Docker calls it the most performant option for Apple Silicon, and it is. The catch is the beta label and that it has no Rosetta.

For Monoceros this lands cleanly: the runtime image and every catalog service (Postgres, Redis, Keycloak, …) ship arm64-native, so on Apple Silicon they run without any emulation. That makes Docker VMM the faster pick with essentially nothing to lose - reach for it if you want maximum speed and can live with a beta. Stay on Apple Virtualization framework if you want the proven default, or if you depend on an amd64-only image (see (2)).

(2) Use Rosetta for x86_64/amd64 emulation. Accelerates amd64 binaries on Apple Silicon, and requires Apple Virtualization framework (it is greyed out under Docker VMM). Because the Monoceros runtime and services are arm64-native, you rarely touch amd64 at all - so this matters only if you deliberately pull an amd64-only image. If you do, keep Rosetta on and stay on Apple Virtualization framework; otherwise it is moot.

(3) File sharing implementation. Pick VirtioFS. It is markedly faster than gRPC FUSE or osxfs (Legacy) for the large directory I/O a dev workspace produces (node_modules, a Maven cache, a target/ folder). VirtioFS only works with a modern VMM (Docker VMM or Apple Virtualization framework), not with the legacy path - which is another reason to leave (1) on one of those two.

Give the VM enough resources

The settings above decide how fast the VM is; this decides how much it can chew at once. A Monoceros workbench often runs several services plus a build in parallel, and the defaults can be tight for that. In Docker Desktop, open Settings then Resources then Advanced:

Docker Desktop Settings, Resources tab: the Advanced resource allocation panel with the CPU limit slider (1) and the memory limit slider (2), plus swap and disk usage limits

(1) CPU limit - how many host cores the VM may use. More cores means faster builds and more headroom when several services run at once. Leaving a core or two for the host keeps the machine responsive.
(2) Memory limit - the ceiling the engine can claim. This is the one most worth raising for a multi-service stack; too low and containers get killed under load (OOM). Note the caveat shown here: on Docker VMM, macOS caps memory at 28 GB or half the system memory, whichever is lower - one more thing to weigh when choosing the VMM in (1).

The Swap and Disk usage limit sliders below rarely need touching; bump disk only if pulling large images or many workbenches starts filling it up.

Windows (WSL)

On Windows, Monoceros runs inside its own managed WSL 2 distro, with Docker Desktop providing the daemon.

File I/O is fast, and you don’t have to arrange it. The classic WSL slowdown comes from working on a Windows drive (/mnt/c, /mnt/d, …), which is roughly an order of magnitude slower to reach from a container than the native Linux filesystem. That does not apply here: Monoceros keeps everything - ~/.monoceros, the materialized workbench, your cloned repos - inside the managed distro’s own ext4 filesystem, so container I/O runs at native Linux speed. There is nothing to configure.

Resources

Unlike macOS, you do not size the VM in Docker Desktop here: with the WSL 2 backend those CPU and memory sliders are disabled, because Docker runs inside WSL and Windows governs WSL’s resources globally. The defaults (WSL may use up to about half the host’s RAM, reclaimed over time) are fine for most work - you only step in to cap a WSL that claims too much, or to raise its ceiling for a heavy multi-service stack.

You tune this through a .wslconfig file in your Windows user folder (C:\Users\<you>\.wslconfig). A sensible starting point:

[wsl2]
memory=8GB
processors=4
autoMemoryReclaim=gradual

memory caps the RAM the WSL VM may take, processors the cores, and autoMemoryReclaim=gradual hands unused RAM back to Windows over time. Apply it once with wsl --shutdown (WSL restarts on next use). These values are an example - adjust them to your machine rather than copying them blind.

In short

Linux: nothing to do.
macOS: a modern VMM with VirtioFS on; give the VM room.
Windows: file I/O is already on the fast WSL filesystem; size resources via .wslconfig, not Docker Desktop.