Documentation on micromux

Introduction

Mon, 01 Jan 0001 00:00:00 +0000

Introduction#

micromux is a local process supervisor with a terminal UI. You describe your dev services in a micromux.yaml, run micromux, and it starts them, tracks their state, and gives you one place to watch logs and restart, enable, or disable them.

The problem#

A local dev stack is several long-lived commands at once — an API, a background worker, a database, a frontend dev server. Two ways people usually run them both fall short:

Installation

Mon, 01 Jan 0001 00:00:00 +0000

Installation#

micromux ships a single binary, micromux. It is developed and fully supported on Linux and macOS; on Windows the TUI runs but the control plane does not (see platform support).

Homebrew#

The quickest way on macOS or Linux:

brew install --cask romnn/tap/micromux

From source#

With a Rust toolchain installed:

cargo install --locked micromux-cli

This builds the full binary, including the MCP server. For a lean, TUI-only build with the MCP server compiled out:

Quick start

Mon, 01 Jan 0001 00:00:00 +0000

Quick start#

This walks through a first config, a first run, and how to read the UI. It assumes micromux is installed.

1. Write a config#

micromux looks for one of micromux.yaml, .micromux.yaml, micromux.yml, or .micromux.yml in the current directory. Create one describing your services:

# yaml-language-server: $schema=https://github.com/romnn/micromux/raw/main/micromux.schema.json
version: "1"
restart: unless-stopped
services:
 api:
 command: ["sh", "-c", "./run-api"]
 env_file: ".env"
 ports: [8080]
 healthcheck:
 test: ["CMD-SHELL", "curl -fsS http://localhost:8080/health || exit 1"]

 worker:
 command: "./run-worker"
 depends_on:
 - name: api
 condition: healthy

The $schema comment turns on completion and validation in editors with the YAML language server. Each service needs a command; everything else is optional. See Configuration for the full set of fields.

The terminal UI

Mon, 01 Jan 0001 00:00:00 +0000

The terminal UI#

Running micromux with no subcommand opens the TUI for the current project. It’s the primary way to watch and steer a stack.

The service sidebar (left) and the selected service’s live logs (right).

Layout#

Sidebar — every service, one row each, showing its lifecycle state: pending, starting, running, healthy, unhealthy, exited, or disabled. The selected row drives the panes on the right.
Log pane — the selected service’s live output. ANSI color and interactive/redrawing output are supported.
Healthcheck pane — toggled with H, it shows the selected service’s latest probe: the command, its exit status, and its output.

Keybindings#

Key	Action
`j` / `k`, `↓` / `↑`	Move the selection
`r`	Restart the selected service
`R`	Restart all services
`d`	Disable / enable the selected service
`a`	Enter PTY input mode — send keystrokes to the service (exit with `Alt+Esc`)
`Tab`	Move focus between panes
`H`	Toggle the healthcheck pane
`w`	Toggle log wrapping
`t`	Toggle follow-tail (stick to the newest logs)
`q` / `Esc`	Quit

Restart, disable, and enable all go through the control plane, so they respect dependency gating and restart policy.

How it compares

Mon, 01 Jan 0001 00:00:00 +0000

How it compares#

micromux sits between two familiar tools. Knowing where it differs makes it clear when to reach for it.

versus Docker Compose#

micromux borrows Compose’s config shape — services, depends_on with conditions, healthcheck, restart, ports, environment, env_file — but it is not a container orchestrator.

Runs host processes. No images, builds, networks, volumes, or container isolation. Your services are the scripts and binaries already on your machine.
Fast local workflow. Start, stop, and restart your existing commands with a UI, no build step in the loop.
Dependency + health gating. Delay a service until its dependencies are started, healthy, or completed — the part a plain process runner lacks.

If you need reproducible environments, networking, volumes, or cross-machine parity, use Docker Compose. If you want to run the processes you already have, quickly and with service awareness, use micromux.