mutti

module
v0.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 27, 2026 License: Apache-2.0

README

mutti

Parallel, isolated Docker Compose environments for every git worktree.

mutti runs one copy of your Compose project per worktree, gives each its own HTTPS hostnames, keeps their data apart, and cleans up after them. Your Compose files stay as they are.

$ mutti worktree add feature-x
Created /home/me/shop-feature-x (branch feature-x).
shop-feature-x is up: https://feature-x.shop.localhost

$ mutti list
NAME            STATUS       BRANCH     URL                               PATH                     PORTS
shop            running 6/6  main       https://shop.localhost            /home/me/shop            db:5432=127.0.0.1:41873
shop-feature-x  running 6/6  feature-x  https://feature-x.shop.localhost  /home/me/shop-feature-x  db:5432=127.0.0.1:52309

Requirements

  • Docker Engine with the Compose plugin (2.24.4 or newer)
  • git
  • Linux. macOS and Windows follow.

Install

Download the archive for your platform from the releases, unpack it and put mutti on your PATH. It is a single static binary. Every archive carries a build provenance attestation:

gh attestation verify mutti_*.tar.gz --repo l0wskilled/mutti

Or with Go: go install github.com/l0wskilled/mutti/cmd/mutti@latest

Once per machine, let your system and browsers trust mutti's local certificate authority:

$ mutti trust

Versioning

mutti follows Semantic Versioning. Before 1.0, a minor release (0.2 to 0.3) may break things and a patch release only fixes them. From 1.0 on, only a major release changes the command line, the --json output or the x-mutti configuration in incompatible ways, and instances made by an older mutti keep working with a newer one.

Quick start

In any directory with a compose.yaml:

$ mutti up        # start this worktree's instance, wait until healthy
$ mutti status    # services, URLs, ports
$ mutti open      # open it in the browser
$ mutti shell api # a shell in the api service, as your user
$ mutti down      # stop it, keep the data

No configuration needed: the service on a typical web port gets https://<project>.localhost, every other HTTP service https://<service>.<project>.localhost; a linked worktree gets https://<worktree>.<project>.localhost. When a worktree is named like a service, the service keeps its hostname and the worktree has to be renamed. Published ports are moved to random ports on 127.0.0.1, so copies of the same project never fight over a port.

mutti init writes these defaults into the Compose file as an x-mutti block to edit from, and a section for AI coding agents into AGENTS.md.

examples/ has small projects to try: no configuration at all, a single-page app with its API on one origin, a full stack with database, hooks and tests, and project commands.

Everyday commands

mutti up / stop / down / destroy start, stop, remove containers (keep data), remove everything
mutti up / stop / restart <service...> the same for single services
mutti list every instance on this machine; --watch keeps it current
mutti events what happens to the instances' containers, as it happens
mutti status this instance, service by service, with a diagnosis of what is not well
mutti diagnose [service...] why services are unhealthy, crashing or gone: health check output, exit codes, last logs
mutti exec <service> -- <cmd> run a command in a service, as your host user
mutti shell [service] interactive shell
mutti logs [service] logs, with the flags of docker compose logs
mutti url / mutti open [service] the URL, or open it
mutti compose <args> any docker compose command against this instance
mutti worktree add <name> new worktree next to the main one, started (--data-from main copies the data)
mutti worktree remove <name> remove instance and worktree; refuses while you have uncommitted changes
mutti reset delete the data and start fresh
mutti run -- <cmd> run a command against a throwaway instance, removed afterwards
mutti tidy remove instances of deleted worktrees, --idle 24h also stops unused ones; shows them first, acts with --yes
mutti doctor check Docker, Compose, router, HTTPS and this project
mutti tui all of the above in a terminal UI

Every command takes --json for scripts and tools; the format is versioned. The full reference is in docs/reference/cli.

Configuration

Optional, in an x-mutti block of your Compose file:

x-mutti:
  main: web
  routes:
    api: { path: /api }          # also https://<instance>.localhost/api
    mail: { host: mailpit }      # https://mailpit.<instance>.localhost
  ports:
    db: [5432]                   # a fixed host port per instance, for database tools
  hooks:
    bootstrap:                   # once per instance
      - service: api
        run: composer install && bin/console doctrine:migrations:migrate -n
  overlays:
    e2e: [compose.e2e.yml]       # mutti up --overlay e2e
  worktree:
    copy: [.env.local]           # copied into new worktrees

All keys: docs/reference/x-mutti.md. For completion and checks in your editor, map your Compose files to docs/reference/compose-with-mutti.schema.json.

MUTTI_INSTANCE, MUTTI_HOSTNAME, MUTTI_HOST_PATH, MUTTI_UID, MUTTI_GID, MUTTI_DOCKER_SOCKET, MUTTI_DOCKER_GID and MUTTI_GIT_COMMON_DIR are available for interpolation, hooks and exec. Two of them are for tool containers:

volumes:
  - ${MUTTI_DOCKER_SOCKET}:/var/run/docker.sock             # the daemon mutti uses, rootless or not
  - ${MUTTI_GIT_COMMON_DIR}:${MUTTI_GIT_COMMON_DIR}         # git in a linked worktree
group_add: ["${MUTTI_DOCKER_GID:-0}"]
Project commands

Scripts in .mutti/commands/host/ run on your machine, scripts in .mutti/commands/<service>/ inside that service; both become mutti <name>. The first # comment is the help text.

Tests and CI

$ mutti run --overlay e2e -- npx playwright test
$ mutti run --overlay e2e --service test-runner -- npm test

mutti run starts a fresh instance with its own data and URL, runs the command, saves the logs of all services to .mutti/local/runs/<id>/ and removes everything, also when mutti is killed. It exits with the command's exit code, so it fits any CI with Docker. Runs in parallel never meet.

mutti also works inside a container (CI steps, tool containers): bind mounts are translated to the paths the Docker host sees, and mutti attach puts the container on the instance's network. Where mutti cannot tell the host path of the worktree, set MUTTI_HOST_ROOT.

The router is one per Docker daemon and serves the certificates of one mutti's local CA. A mutti in a container that should use the same router as mutti on the host needs the host's state: mount ~/.mutti to the same place in the container. Otherwise it refuses to touch the host's router; MUTTI_ROUTER_NAME, MUTTI_HTTP_PORT and MUTTI_HTTPS_PORT give it a router of its own.

Terminal UI

mutti tui shows every instance on this machine, the services of the selected one and what is wrong with them, kept current as containers change. Every service shows its CPU and memory with a sparkline; the selected one also its image, uptime, restarts and last health check. The header tells whether Docker answers and the router runs, the footer every key of the pane with the focus. A terminal narrower than 90 columns shows one pane at a time.

Keys act on the selected instance or service, or on the services marked with space: up, stop, restart, logs, diagnose, shell, exec, open, copy URL, new worktree, down, reset and destroy, which removes an instance whatever state it is in, also when its worktree is gone. T tidies what deleted worktrees left behind, / filters the instances by name or branch. Logs stream as the services print them, and / there keeps the lines with the text typed. : searches every mutti command and subcommand, the project's own commands included, and runs it; ? lists the keys. The mouse selects with a click and scrolls with the wheel; most terminals select text with shift held.

Web UI

$ mutti serve --open
mutti serves http://127.0.0.1:7477 (Ctrl-C to stop)

Every instance on this machine, kept current as containers change: status, branch, URLs and ports, starting, stopping and removing single services or all of them, a diagnosis of what is not well, events, and logs that stream in live and stay whole and scrollable however long they get. It runs in the foreground like any other command, answers only on 127.0.0.1, and serves the same data as JSON under /api and the tools of mutti mcp under /mcp.

AI coding agents

mutti mcp serves mutti as a Model Context Protocol server: agents get tools to start and inspect environments, run commands in services, run tests against throwaway copies and open worktrees with environments of their own, so several agents can work in parallel.

$ claude mcp add mutti -- mutti mcp

mutti init also writes a section on the environment into AGENTS.md, which most agents read.

How it works

  • Identity. Each worktree gets a name once and keeps it, also when you rename the directory, switch branches or git worktree move it. It is stored in the worktree's git directory, not in your files.
  • State lives in Docker. Instances are found through labels; there is no database to get out of sync.
  • One router per machine. A Traefik container on 127.0.0.1 routes hostnames to instances. Each instance has its own network; the router joins them all, the instances never meet. Inside an instance's containers its hostnames resolve to the router as well, so a test browser in a container uses the same URLs. Clients that map *.localhost to loopback by themselves (Chromium, curl) need the address handed over, e.g. --host-resolver-rules or --resolve.
  • Throwaway runs are guarded by a reaper container that removes them when mutti is gone.

Development

$ make hooks       # run the checks on every commit and push
$ make check lint  # format, generated docs, vet, lint, unit tests
$ make cover       # unit + integration tests against Docker, 100% coverage required
$ make test-e2e    # end-to-end tests with the real binary
$ make docs        # regenerate docs/reference

A release is a tag vX.Y.Z on main: the release workflow runs all checks, builds the archives and publishes them with their changelog.

Directories

Path Synopsis
cmd
mutti command
Command mutti runs parallel, isolated Docker Compose environments per git worktree.
Command mutti runs parallel, isolated Docker Compose environments per git worktree.
mutti-docs command
Command mutti-docs regenerates docs/reference (make docs).
Command mutti-docs regenerates docs/reference (make docs).
internal
app
Package app holds mutti's use cases (up, down, list, ...).
Package app holds mutti's use cases (up, down, list, ...).
apptest
Package apptest builds an app.App on fakes over a real git repository, for the tests of the packages that serve the app: command line, MCP, HTTP.
Package apptest builds an app.App on fakes over a real git repository, for the tests of the packages that serve the app: command line, MCP, HTTP.
cli
Package cli maps mutti's commands and flags onto the use cases in app and renders their results.
Package cli maps mutti's commands and flags onto the use cases in app and renders their results.
compose
Package compose runs the user's installed `docker compose` CLI.
Package compose runs the user's installed `docker compose` CLI.
compose/composetest
Package composetest provides a compose.Runner that simulates `docker compose` on top of the in-memory engine from enginetest.
Package composetest provides a compose.Runner that simulates `docker compose` on top of the in-memory engine from enginetest.
docgen
Package docgen generates the reference documentation from the code, so it cannot drift: the CLI reference from the cobra commands, and the x-mutti reference and JSON Schemas from the configuration structs and their comments.
Package docgen generates the reference documentation from the code, so it cannot drift: the CLI reference from the cobra commands, and the x-mutti reference and JSON Schemas from the configuration structs and their comments.
engine
Package engine is mutti's narrow view of the Docker Engine API.
Package engine is mutti's narrow view of the Docker Engine API.
engine/enginetest
Package enginetest provides an in-memory engine.Engine and a contract suite that keeps it honest: the same suite runs against the fake and against a real daemon.
Package enginetest provides an in-memory engine.Engine and a contract suite that keeps it honest: the same suite runs against the fake and against a real daemon.
extend
Package extend finds the extensions a project or user adds to mutti without changing it: custom commands in .mutti/commands.
Package extend finds the extensions a project or user adds to mutti without changing it: custom commands in .mutti/commands.
gitdir
Package gitdir asks the installed git binary where a worktree and its admin directories are.
Package gitdir asks the installed git binary where a worktree and its admin directories are.
home
Package home resolves ~/.mutti, the directory mutti keeps its own files in: the local CA, the router's configuration, locks and the user's own commands.
Package home resolves ~/.mutti, the directory mutti keeps its own files in: the local CA, the router's configuration, locks and the user's own commands.
hostenv
Package hostenv tells whether mutti runs inside a container and maps paths of that container to paths on the Docker host, which is what the daemon needs for bind mounts.
Package hostenv tells whether mutti runs inside a container and maps paths of that container to paths on the Docker host, which is what the daemon needs for bind mounts.
identity
Package identity derives, stores and validates instance names.
Package identity derives, stores and validates instance names.
lock
Package lock provides host-wide, cross-process locks backed by flock(2).
Package lock provides host-wide, cross-process locks backed by flock(2).
mcpserver
Package mcpserver offers mutti's use cases as tools of a Model Context Protocol server, for AI coding agents: start and inspect environments, run commands and tests in them.
Package mcpserver offers mutti's use cases as tools of a Model Context Protocol server, for AI coding agents: start and inspect environments, run commands and tests in them.
project
Package project finds a project's Compose files and reads its x-mutti configuration.
Package project finds a project's Compose files and reads its x-mutti configuration.
reaper
Package reaper talks to Ryuk, the Testcontainers resource reaper: a container that removes everything matching the filters it was given once its client's connection is gone.
Package reaper talks to Ryuk, the Testcontainers resource reaper: a container that removes everything matching the filters it was given once its client's connection is gone.
router
Package router describes mutti's machine-wide reverse proxy: one Traefik container that owns the HTTP(S) ports on loopback and routes hostnames to instances.
Package router describes mutti's machine-wide reverse proxy: one Traefik container that owns the HTTP(S) ports on loopback and routes hostnames to instances.
server
Package server serves mutti over HTTP on the loopback interface: a web UI, a JSON API with the envelopes of --json, server-sent events, and the MCP server for agents that speak HTTP.
Package server serves mutti over HTTP on the loopback interface: a web UI, a JSON API with the envelopes of --json, server-sent events, and the MCP server for agents that speak HTTP.
tlsca
Package tlsca runs mutti's local certificate authority: one root per machine, one leaf certificate per instance.
Package tlsca runs mutti's local certificate authority: one root per machine, one leaf certificate per instance.
tui
Package tui is mutti's terminal UI: every instance at a glance, its services, what is wrong with them, and every mutti command a key or a short search away.
Package tui is mutti's terminal UI: every instance at a glance, its services, what is wrong with them, and every mutti command a key or a short search away.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL