Docker

Microgamma ships as a public, multi-architecture Docker image on GitHub Container Registry, so you can run it headless in a container on any host. Inside the container, prefix any CLI command with mg; running with no command launches the app headless.

Keep your configuration in a named volume so it survives restarts, and mount your music library at /music.

1. Pull the image

Pull the plain :latest tag and Docker automatically selects the right build for your architecture (Intel or Apple Silicon / ARM):

docker pull ghcr.io/microgamma/microgamma-desktop:latest

Pin a specific version with a versioned tag instead:

docker pull ghcr.io/microgamma/microgamma-desktop:v2.94.3

Per-architecture tags (latest-x64, latest-arm64, v2.94.3-x64, …) also exist if you need to pin a specific build, but the plain tag is what most people want.

2. First-run setup

Run the interactive wizard once — device name, music location, login, and scan. It needs an interactive terminal, so pass -it:

docker run -it --rm \
  -v mg-config:/home/node/.microgamma \
  -v /path/to/music:/music \
  ghcr.io/microgamma/microgamma-desktop:latest \
  mg setup

3. Run headless

Start the app in the background, reusing the mg-config volume from setup:

docker run -d \
  --name microgamma \
  -v mg-config:/home/node/.microgamma \
  -v /path/to/music:/music \
  ghcr.io/microgamma/microgamma-desktop:latest

Running other commands

You can run any mg command the same way. For example, to rebuild the library index:

docker run --rm \
  -v mg-config:/home/node/.microgamma \
  -v /path/to/music:/music \
  ghcr.io/microgamma/microgamma-desktop:latest \
  mg scan --reset

Ports

The image doesn't publish any ports, and it doesn't need to. The song file server binds to an unused port and tells the web client which one. Remote access through play.microgamma.io is brokered by Microgamma's signaling service.