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:

Services

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

Services#

Every entry under services: is one supervised process. Its key (api, worker, …) is the service id used everywhere else — in depends_on, in the TUI, and in micromux ctl. Only command is required.

services:
 api:
 name: API server  # optional display name for the TUI
 command: ["sh", "-c", "./run-api"]
 working_dir: ./services/api
 environment:
 APP_ENV: development
 PORT: "8080"
 env_file: .env
 ports: [8080]

Command#

command is either a shell-like string or an argv-style array:

The control plane

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

The control plane#

The control plane is the local endpoint every running micromux opens. The TUI, the MCP server, and the micromux ctl client all speak to it, so any of them can inspect and steer a session with identical semantics.

`micromux ctl`#

ctl is the shell client — the same control plane an agent uses, dogfooded from your terminal. It targets the session for the config resolved from the current directory (or one you name with --session).

Dependencies & startup order

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

Dependencies & startup order#

depends_on gates a service’s startup on the state of other services. This is the difference between a wall of panes that all launch at once and a stack that comes up in the right order.

services:
 api:
 command: "./run-api"
 depends_on:
 - name: postgres
 condition: healthy
 - name: migrate
 condition: completed

 postgres:
 command: "postgres -D ./pgdata"
 healthcheck:
 test: ["CMD-SHELL", "pg_isready -q"]

 migrate:
 command: "./migrate"
 restart: "no"

Here api starts only once postgres is healthy and migrate has completed successfully.

Dynamic services

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

Dynamic services#

Beyond the services declared in micromux.yaml, the control plane can create runtime (dynamic) services — processes an agent starts on the fly, for example to run a one-off script or bring up a helper alongside your stack. They are disabled by default and bounded by an explicit policy, because a runtime service is a same-user command with real blast radius.

Enabling them#

Runtime services are off until you opt in, in the target session’s config. The policy is latched when the session starts, so changing it requires a session restart:

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:

Healthchecks

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

Healthchecks#

A healthcheck is a command micromux runs periodically to decide whether a service is healthy. Health drives two things: how the service is shown in the UI, and whether depends_on … condition: healthy gates are satisfied.

services:
 api:
 command: "./run-api"
 healthcheck:
 test: ["CMD-SHELL", "curl -fsS http://localhost:8080/health || exit 1"]
 start_delay: "2s"
 interval: "10s"
 timeout: "2s"
 retries: 3

The probe#

test is the command to run, in the same string-or-array form as a service command. The Compose-style CMD-SHELL prefix runs the rest through a shell:

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.

Restart policies

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

Restart policies#

A restart policy decides what micromux does when a service’s process exits. Set it globally, per service, or both — a service inherits the top-level default and overrides it if it sets its own.

restart: unless-stopped  # default for all services
services:
 api:
 command: "./run-api" # inherits unless-stopped
 migrate:
 command: "./migrate"
 restart: "no" # one-shot
 flaky:
 command: "./flaky"
 restart: on-failure:5  # up to 5 retries on non-zero exit

Policies#

Policy	Behavior
`always`	Restart whenever the process exits, whatever the exit status.
`unless-stopped`	Restart on exit, unless you disabled/stopped the service yourself.
`on-failure`	Restart only on a non-zero exit. Add a cap with `on-failure:N` (e.g. `on-failure:5`).
`no`	Never restart. Use for one-shot jobs like migrations. (`never` is accepted as a synonym.)

on-failure may be written with a count as on-failure:3 or on-failure=3. Policy names are case-insensitive and accept - or _ (unless-stopped or unless_stopped).

Logs

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

Logs#

micromux captures each service’s output two ways at once:

an in-memory tail — bounded and fast, backing the TUI and the default log stream;
disk-backed run logs — the full output of recent runs, retained so you can inspect crash output after a restart.

logs:
 retained_runs: 5 # full disk-backed runs kept, including the current one
 memory:
 max_lines: 1000
 max_bytes: 67108864 # 64 MiB

services:
 api:
 command: "./run-api"
 logs:
 retained_runs: 10 # overrides the global default for this service

Retained runs#

retained_runs (aliases: runs, history; default 5) is how many full service runs are kept on disk, counting the current run. Each restart starts a new run; when the count is exceeded the oldest run is dropped. This is what lets an agent read the logs of the run that crashed even though the service has since restarted. Disk run logs hold the full output and rotate only by run count.

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.

Configuration reference

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

Configuration reference#

Every key in micromux.yaml. The machine-readable source of truth is micromux.schema.json; reference it from your config for editor completion and validation:

# yaml-language-server: $schema=https://github.com/romnn/micromux/raw/main/micromux.schema.json

Top level#

Key	Type	Default	Description
`version`	string / number	—	Config format version. Use `"1"`.
`name`	string	directory name	Session name surfaced to agents via the control plane.
`strict`	bool	`false`	Treat config warnings as errors.
`services`	map	—	Service definitions, keyed by id.
`restart`	string	—	Default restart policy.
`healthcheck`	object	—	Default healthcheck timing (no `test`).
`logs`	object	—	Default log retention.
`ui`	object	—	Terminal-UI options.
`control`	object	—	Control plane and dynamic-service policy.

`services.<id>`#

Key	Type	Description
`command`	string / array	Required. Shell-like string or argv array.
`name`	string	Display name for the TUI.
`disabled`	bool	Leave the service disabled when the session starts.
`working_dir`	string	Working directory, relative to the config. Aliases: `cwd`, `directory`.
`environment`	map	Inline environment variables.
`env_file`	string / object / array	`.env` file(s) to load. Long form is `{ path: … }`.
`depends_on`	array	Dependencies; each a service id or `{ name, condition }`.
`healthcheck`	object	A probe with `test` plus timing.
`ports`	array	Ports the service uses (metadata; not bound by micromux).
`restart`	string	Restart policy for this service.
`logs`	object	Log retention for this service.
`color`	bool	Force color handling for this service.

`depends_on[]`#

A bare string (the started condition) or an object:

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.

micromux

Introduction

Introduction#

The problem#

Services

Services#

Command#

The control plane

The control plane#

micromux ctl#

Dependencies & startup order

Dependencies & startup order#

Dynamic services

Dynamic services#

Enabling them#

Installation

Installation#

Homebrew#

From source#

Healthchecks

Healthchecks#

The probe#

Quick start

Quick start#

1. Write a config#

Restart policies

Restart policies#

Policies#

Logs

Logs#

Retained runs#

The terminal UI

The terminal UI#

Layout#

Keybindings#

Configuration reference

Configuration reference#

Top level#

services.<id>#

depends_on[]#

How it compares

How it compares#

versus Docker Compose#

`micromux ctl`#

`services.<id>`#

`depends_on[]`#