Configuration on micromux

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:

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.

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:

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.

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:

Configuration on micromux

Services

Services#

Command#

Dependencies & startup order

Dependencies & startup order#

Healthchecks

Healthchecks#

The probe#

Restart policies

Restart policies#

Policies#

Logs

Logs#

Retained runs#

Configuration reference

Configuration reference#

Top level#

services.<id>#

depends_on[]#

`services.<id>`#

`depends_on[]`#