Set up a project

Install mm first. For a complete example with workstation setup, follow First local app.

New project#

From the directory containing your Compose files, preview the generated setup:

mm init --name example

Replace example with your project name. mm finds services, build settings, ports, environment templates, and possible development mounts. Review the proposed file changes, then use the printed hash to create them:

mm init --name example --plan PLAN_HASH --yes

The review includes a project .gitignore update for /.config/mm.overrides.yaml, preserving existing rules. You can create that optional file later for local configuration overrides.

Open .config/mm.yaml and check the image repositories, environment bindings, routes, and mounts. Generated guesses may need editing. See where configuration belongs.

mm config validate
mm env setup
mm secret status

Resolve missing values before building. If the project uses Age secrets:

mm secret init age
mm secret generate --missing

generate --missing creates values only for secrets with a configured generator. For other values, use mm secret set KEY and enter the value at the hidden prompt.

Existing clone#

Repositories initialized before local overrides were supported should add and commit /.config/mm.overrides.yaml to their project .gitignore once. Existing projects use the setup flow below; mm init is for creating a project configuration.

From the project directory, check what is needed on this workstation:

mm dev setup project
mm env setup
mm secret status

Follow the project's instructions for runtime selection and secret providers. Set a missing secret without putting its value in shell arguments:

mm secret set database.password

Replace database.password with the name reported by mm secret status.

Build and run#

For projects with their own images, publish a matching build before deploying:

mm build --publish plan
mm build --publish apply --plan BUILD_PLAN_HASH --yes
mm deploy plan
mm deploy apply --plan DEPLOY_PLAN_HASH --yes
mm service status

Use each plan's printed hash. Builds require Docker Buildx, registry access, and a clean full Git checkout. Skip the build commands for projects using only third-party images. See build and deploy.

The project-setup command can also apply a reviewed setup and deployment together:

mm dev setup project --plan WORKFLOW_HASH --deploy-plan DEPLOY_HASH --yes

Use the setup hash from mm dev setup project and the deployment hash from mm deploy plan. This does not build missing images. Regenerate both reviews if either becomes stale.

Guided terminal#

Run mm in an interactive terminal and open Guided for workstation setup, new projects, existing clones, and project editing. Scripts should use explicit subcommands instead.

Automation#

Place --output json before the subcommand:

mm --output json config validate
mm --output json deploy plan
mm --output json deploy apply --plan "$PLAN_HASH" --yes

Check the command's exit status as well as its JSON. Use --yes for required confirmation and --stdin for secret input:

printf '%s' "$DATABASE_PASSWORD" | mm secret set database.password --stdin

Combined dev setup --services is not supported in JSON mode. Split it into setup and shared-service commands:

mm --output json dev setup
mm --output json --runtime docker-compose dev services plan
mm --output json --runtime docker-compose dev services apply \
  --plan "$SERVICES_PLAN_HASH" --yes

Use the runtime that owns your local services throughout.