Headless Mode

Microgamma can run without a graphical window — ideal for a home server, a NAS, or a Raspberry Pi. In headless mode the app runs hidden but its streaming servers stay up, so you can still reach your library from any device. You handle setup, login, and scanning from the command line — every command is listed in the CLI Reference.

Two executables

Microgamma ships as two programs that live side by side:

• Microgamma — the app itself. Launch it with --headless to run without a window. It takes no other options.
• mg — the command-line tool. Everything else — logging in, setting the device name and music folder, and scanning your library — happens through mg.

1. First-run setup

The quickest path is the interactive setup, which walks through device name, music folder, login, and an initial scan in one go:

mg setup

Prefer to do it step by step? The individual commands are below.

Log in

mg login

This starts a device-code login: it prints a URL and a short code. Open the URL in any browser, enter the code, and approve. The access token is saved to your config directory and reused on every launch. mg logout removes it.

Configure

mg config --device-name "Living Room" --music-path /home/user/Music

The device name is how this machine shows up when you connect from another device; the music path is the folder Microgamma reads your music from. Short flags -n and -m work too. Run mg config with no options to print the current device name, device ID, and music path.

Scan your library

mg scan

Scans the configured music folder into the library. Pass a path to scan somewhere else, or --reset (-r) to rebuild the database from scratch. While the app is running it also watches the folder and picks up added or removed tracks automatically ( mp3, flac, ogg, wav).

2. Run headless

Microgamma --headless

Same application, window hidden — the streaming servers start as usual. On Linux (and inside containers) Chromium still needs a display even when the window is hidden, so run it under a virtual framebuffer and disable the sandbox:

xvfb-run -a Microgamma --no-sandbox --headless

On a server without a GPU, also pass --disable-gpu --disable-dev-shm-usage to avoid a Chromium GPU-process crash. (The Docker image already applies these for you.)

Leave it running under whatever supervisor you like — a systemd service, tmux, or a container. For the container route, see the Docker guide.

3. Reach it from anywhere

Open play.microgamma.io and log in with the same account. Your headless device appears in the list, and from there you can remote-control it or stream to the device you're on. Connections are brokered through Microgamma's signaling service, so this works across networks without port-forwarding or opening ports on your router.

Where configuration lives

By default everything is stored in ~/.microgamma — the device config, settings, and your auth token, each as a small JSON file. Point Microgamma somewhere else with the MG_BASE_PATH environment variable:

MG_BASE_PATH=/srv/microgamma mg config

An absolute path is used as-is; a relative value is treated as a folder name under your home directory. Set the same value for both mg and Microgamma so they share one configuration.

Ports

Headless Microgamma listens on 3333 (the song file server). On a machine behind a home router you generally don't need to open it — peer and remote access are brokered by the signaling service over WebRTC, with no fixed inbound port — but keep 3333 free if you run other services on the same host.