Skip to content

Configuration

mothership.yaml

workspace: my-platform

# Optional: wraps all task execution with a secret manager
env_runner: "dotenvx run --"

# Optional: branch naming pattern ({slug} is replaced)
branch_pattern: "feat/{slug}"

repos:
  shared:
    path: ./shared
    type: library            # "library" or "service"
    depends_on: []
    env_runner: "op run --"  # per-repo override
    tasks:
      test: unit             # override canonical task name
  auth-service:
    path: ./auth-service
    type: service
    depends_on: [shared]

Secret management (env_runner)

Mothership doesn't manage secrets. It delegates to your secret manager via env_runner:

Tool Config value
dotenvx dotenvx run --
Doppler doppler run --
1Password CLI op run --
Infisical infisical run --
None omit env_runner

Monorepo support (git_root)

For monorepos where multiple services share one git repo, use git_root to declare subdirectory services:

repos:
  backend:
    path: .
    type: service
  web:
    path: web              # relative — required; interpreted against backend's worktree
    type: service
    git_root: backend      # backend is auto-ordered before web (no depends_on needed)

Rules: - git_root must reference another repo in the workspace. - The referenced repo cannot itself have git_root set (no chaining). - A git_root child's path must be relative and must not contain ..; an absolute path would resolve to the source checkout instead of the task worktree and is rejected at config load. - A git_root parent is auto-ordered before its children — it is materialized first automatically, so you do NOT need to hand-add depends_on: [parent]. (Declaring parent depends_on child is the opposite order and is rejected as a dependency cycle.) - The subdirectory must exist. It must contain a go-task file (Taskfile.yml, Taskfile.yaml, or another resolution-set spelling) unless it uses only installed backends and declares no project tasks. - Subdirectory services still have their own depends_on, tags, tasks, and start_mode.

Service start modes (start_mode)

For long-running services, set start_mode: background:

repos:
  infra:
    path: ./infra
    type: service
    start_mode: background     # mship run launches and moves on
  backend:
    path: ./backend
    type: service
    start_mode: background
    depends_on: [infra]

With start_mode: background, mship run launches the service and continues to the next dependency tier without waiting for exit. Background services keep running until Ctrl-C propagates SIGINT through go-task to their child processes. start_mode only affects mship run. Tests and logs always run foreground.

Healthchecks

For services that need time to become ready, declare a healthcheck. mship run waits for the healthcheck to pass before starting dependent services.

repos:
  infra:
    path: ./infra
    type: service
    start_mode: background
    healthcheck:
      tcp: "127.0.0.1:8001"          # wait for port to accept connections
      timeout: 30s                    # optional, default 30s
      retry_interval: 500ms           # optional, default 500ms

  backend:
    path: ./backend
    type: service
    start_mode: background
    depends_on: [infra]
    healthcheck:
      http: "http://localhost:8000/health"

  web:
    path: ./web
    type: service
    start_mode: background
    depends_on: [backend]
    healthcheck:
      sleep: 3s                        # unconditional wait

  custom:
    path: ./custom
    type: service
    start_mode: background
    healthcheck:
      task: wait-for-custom            # runs `task wait-for-custom`; 0 exit = ready

Probe types: tcp, http, sleep, task (any one per healthcheck). Exactly one probe per healthcheck. If the probe doesn't succeed within timeout, the service is treated as failed and mship run exits non-zero. Healthchecks apply to mship run only.

Task name aliasing

If your Taskfile uses different task names than mothership's defaults (test, run, lint, setup), add a tasks: mapping:

repos:
  my-app:
    path: .
    type: service
    tasks:
      run: dev                 # mship run → task dev
      test: test:all           # mship test → task test:all
      lint: lint:all
      setup: infra:start

mship doctor respects the mapping when checking for standard tasks.

Taskfile contract

Repos that use mship's ordinary task execution need a Taskfile.yml with standard task names. Mship calls task <name> in each repo. Override names per repo in the tasks mapping. Default tasks: test, run, lint, logs, setup. Missing tasks are skipped gracefully. A repo using only a packaged run_backends builtin does not need a Taskfile for discovery or inherited backend operations.

Run backends

run_backends is a per-repo map of project backend names to target adapters. The name is part of the project's configuration contract: profiles and host-local bindings refer to that name, rather than to an SDK serial number, browser path, or device identifier.

Mship bundles five adapters: android, flutter, ios, browser, and platformio. They are installed with mship; selecting one does not copy adapter code into your repository.

Builtin only

A builtin needs only configuration. It does not need a project Taskfile.yml, a discovery task, or an operation wrapper:

repos:
  mobile:
    path: apps/mobile
    type: service
    run_backends:
      android-local:
        builtin: android
      flutter-local:
        builtin: flutter

  web:
    path: apps/web
    type: service
    run_backends:
      checked-browser:
        builtin: browser

  firmware:
    path: firmware
    type: service
    run_backends:
      prepared-board:
        builtin: platformio

The adapter runs from the same installed Python runtime as the mship session. Do not make a second virtual environment, call an arbitrary python, or vendor the adapter into the project just to select a builtin.

Native session ownership is fixed by the builtin catalog: android and flutter use the native session owner; ios, browser, and platformio do not. A configuration cannot replace that owner. This protects the existing process/device-session authority and is especially important for Flutter, which must preserve the Android framework owner instead of creating a parallel one.

Extending a builtin with tasks

Use discover_task and/or operations only for actions that the project needs to replace. The configured values are ordinary keys in that repo's tasks: map; omitted actions inherit the selected builtin's implementation.

repos:
  mobile:
    path: apps/mobile
    type: service
    tasks:
      discover-signed-flutter: discover-signed-flutter
      capture-signed-flutter: capture-signed-flutter
    run_backends:
      signed-flutter:
        builtin: flutter
        discover_task: discover-signed-flutter
        operations:
          capture: capture-signed-flutter

The corresponding task can add project policy and then delegate back to the installed implementation:

# Taskfile.yml
version: '3'

tasks:
  discover-signed-flutter:
    cmds:
      - '"{{.MSHIP_SESSION_PYTHON}}" -I -m mship.backends flutter discover'
  capture-signed-flutter:
    cmds:
      - '"{{.MSHIP_SESSION_PYTHON}}" -I -m mship.backends flutter'

discover is explicit only for discovery. Operation requests are sealed by mship, so a delegated operation receives its requested action from the private request/context files rather than from caller-provided shell arguments. An override must consume the supplied sealed files and must preserve the builtin's framework/session ownership; it must not synthesize target context, choose a different device, or start its own framework owner.

Custom task routing and fully custom backends

The existing custom form remains available: omit builtin, supply a discovery task and operation tasks, and keep the routing in the project. The following is a runnable custom-routing configuration: its tasks deliberately use the installed browser protocol implementation, but the configuration has no builtin field and mship dispatches through the project's normal Taskfile keys.

repos:
  web:
    path: apps/web
    type: service
    tasks:
      discover-project-browser: discover-project-browser
      run-project-browser: run-project-browser
    run_backends:
      project-browser:
        discover_task: discover-project-browser
        operations:
          run: run-project-browser
# Taskfile.yml
version: '3'

tasks:
  discover-project-browser:
    cmds:
      - '"{{.MSHIP_SESSION_PYTHON}}" -I -m mship.backends browser discover'
  run-project-browser:
    cmds:
      - '"{{.MSHIP_SESSION_PYTHON}}" -I -m mship.backends browser'

For a backend that is entirely project-owned, keep the same configuration shape but point those task keys at the project's real protocol implementation. That implementation must consume the sealed request/context/bindings files and return the existing discovery and operation protocol; mship does not generate, ship, or infer it. Omit session_owner unless that implementation is a compatible Android or Flutter native owner; then explicitly set session_owner: android or session_owner: flutter. Native physical iOS operations remain unsupported until a concrete owner is designed.

Bindings, prerequisites, and safety

Host-private target bindings stay keyed by the project backend name (for example signed-flutter or lab-rig), not by a builtin name. They are carried through MSHIP_TARGET_BINDINGS_FILE; keep the file, target IDs, SDK paths, and credentials out of committed YAML and normal command output. Mship also provides MSHIP_TARGET_REQUEST_FILE and MSHIP_TARGET_CONTEXT_FILE. Treat all three as private, sealed inputs; do not reconstruct their contents from CLI arguments or ambient environment.

Builtins do not install external tooling. Prepare the required SDK/toolchain on the selected host before use: Android SDK/adb for Android, Flutter plus its prepared platform toolchain for Flutter, Xcode/simctl on macOS for iOS, an installed/configured browser driver and engine for browser targets, and PlatformIO plus the selected board/serial permissions for PlatformIO. Discovery is read-only: it must not boot hardware, install dependencies, launch a browser, flash a board, or upload firmware. Operations may require the corresponding prepared external tool, and unsupported capability/driver combinations report an actionable error rather than silently falling back to another target.

Evidence storage (evidence_storage)

Storage mode for acceptance-criterion artifact evidence: published, local, or encrypted. When unset it inherits spec_storage, mapping that field's committed to published — a spec is committed into the workspace repo's tree, whereas evidence is published onto an orphan branch in the repo whose PR embeds it. Inheriting is what you want unless the cost profiles genuinely differ — prose is bytes, screenshots are megabytes, so spec_storage: committed with evidence_storage: local is a reasonable pairing.

Evidence may never be more exposed than its spec. Ordering the modes published > encrypted > local, a configuration where evidence outranks the spec is refused at config load: a plaintext screenshot beside an encrypted spec discloses exactly what the encryption was protecting.

evidence_storage: local   # inherits spec_storage when omitted

Embedding evidence in a pull-request body requires published — the other two modes aren't fetchable by GitHub, so the PR names the artifact instead of showing it. Embedding therefore means the screenshots are readable by anyone who can read the repo the pull request targets.

Product assumptions (assumption_storage, assumption_gate)

The product-assumptions system (#444) makes agents explicitly disposition the assumptions a plan is built on. Two workspace-level fields govern it:

assumption_storage — where this workspace's L1 assumptions doc (docs/product_assumptions.md) lives, mirroring spec_storage's modes: committed (default, plaintext + pushed), local (plaintext but git-ignored), or encrypted (Fernet ciphertext, unreadable without .mothership/spec-key). Applied transparently by core/assumptions.py; an invalid value fails loud at config load.

assumption_gate — the L4 plan→dev gate. off (default) enforces nothing: merging the feature does not change existing behaviour, so the gate rolls out dark. enforce additionally requires a fresh, fully-approved PlanCheckResult before a feature WorkItem may transition plan → dev — every assumption the checker flagged as not-covered (or left un-dispositioned) must carry an explicit mship plan assumptions approve <axis> sign-off. Freshness is plan-hash bound, so editing the plan after a check re-arms the gate.

assumption_storage: committed   # committed | local | encrypted
assumption_gate: off            # off | enforce

Workspace-level fields

Top-level keys on mothership.yaml (alongside workspace, env_runner, branch_pattern, audit, and repos, all covered above):

Field Meaning
default_scope Default repo scope for mship spawn when --repos is omitted. "all" (default) uses every repo; "none" requires an explicit --repos; a list of repo names uses just those. (#74)
spawn_confirm_threshold If set and a no---repos spawn's effective scope exceeds N repos, require confirmation (TTY) or --yes (non-TTY). Unset by default. (#74)
spec_paths Workspace-relative paths searched for specs by mship phase dev's soft gate and mship view spec. Default: ["docs/superpowers/specs"]. (#113)
require_approved_spec When true, mship phase dev hard-blocks plan → dev unless a bound, approved spec exists. Default: false. (MOS-151)
docs_dir Workspace-relative directory where the bundled skills write plan docs; plans live at <docs_dir>/plans/. Default: "docs". Does not affect canonical specs (always specs/).
default_remote Host-agnostic base URL prefix used to resolve a member's clone URL when its url is a bare name or omitted (member name appended). Enables mship bootstrap from a fresh clone. (MOS-180)
relay Reverse-tunnel relay connection for mship serve --relay (see relay-hosting.md).
run_hosts Logical run-host role names available to the workspace (only the names are committed here). A repo opts into one via its run_host; each machine maps the role to a concrete {url, token} in the gitignored .mothership/run-hosts.yaml.
redact Extra mship export --redacted regex patterns, unioned with the built-in set. (MOS-102)
lifecycle_hooks Declarative reactions to task / WorkItem / PR lifecycle transitions. Named lifecycle_hooks (not hooks) to disambiguate from the git commit/push hooks. (MOS-220)
lifecycle_hooks_default_timeout Fallback per-hook timeout in seconds when a lifecycle_hooks: entry omits timeout. Default: 30.
dispatch_models Per-mode model map for mship dispatch (implementer / reviewer / standalone). Precedence: --model flag > this map > built-in defaults; every built-in mode defaults to inherit. The sentinel means harness default behavior: the adapter omits its model selector. Explicit configured values are emitted verbatim and require a selector-capable harness adapter; an adapter without a selector rejects them rather than substituting another model.
workspace: my-platform
default_scope: none               # force explicit --repos on every spawn
spawn_confirm_threshold: 3        # confirm a no-flag spawn touching >3 repos
require_approved_spec: true       # gate plan -> dev on an approved spec
docs_dir: docs                    # plans land in docs/plans/
default_remote: https://github.com/atomikpanda   # bootstrap members from bare names

relay:
  host: relay.example.com
  ssh_port: 2222                  # optional, default 2222
  user: tunnel                    # optional; omit for the ssh default

run_hosts: [ios-sim-host, android-emu-host]   # role names; connections live in .mothership/run-hosts.yaml

redact:
  patterns:
    - "sk-[A-Za-z0-9]{20,}"                    # bare string -> a "custom" pattern
    - { name: internal-host, pattern: "corp\\.example\\.internal" }

lifecycle_hooks:
  - on: pr.merged                 # a lifecycle event (phase.entered.*, workitem.phase.*, task.finished/closed, pr.merged/closed)
    run: notify-slack             # a go-task target or shell command
    repo: backend                 # optional: run in this repo's worktree
    timeout: 60                   # optional: overrides lifecycle_hooks_default_timeout
    # required: true              # only valid on the pre-mutation events (phase.entered.* / workitem.phase.*)

Per-repo fields

Additional keys on each entry under repos: (alongside path, type, depends_on, env_runner, tasks, run_backends, git_root, start_mode, and healthcheck, covered above):

Field Meaning
not_applicable Canonical task names that don't apply to this repo (e.g. [lint]). Skipped without warning; cannot overlap with tasks. (#76)
tags Free-form tags for filtering repos via --tag (mship test/run/build).
symlink_dirs Directories symlinked into each task worktree from the source repo (re-synced by mship bind refresh).
bind_files Files (relative paths or globs, must stay inside the repo) copied into each task worktree from the source repo (re-synced by mship bind refresh).
base_branch Default PR base branch for this repo (overridden by mship finish --base / --base-map; falls back to the remote default branch).
expected_branch Branch the repo's main checkout is expected to be on; drift audit flags unexpected_branch otherwise.
url Explicit clone URL for mship bootstrap (overrides default_remote + name). Non-GitHub members set a full URL here.
allow_dirty Allow a dirty worktree without failing the drift audit. Default: false.
allow_extra_worktrees Allow extra worktrees on the repo without failing the drift audit. Default: false.
capture UI-capture config — a platforms: list mship capture can target (--platform required when more than one).
run_host Logical run-host role this repo uses for --remote execution (mship build/capture). Must name an entry in the workspace run_hosts: list.
setup_inputs Manifests/lockfiles whose content decides whether a remote run re-runs task setup on the run host (glob patterns, matched inside the materialized worktree). Undeclared means setup runs on first materialization only — declaring them is what enables re-run-on-change. See remote-run.md.
host_tools Optional strict selected-host mise declaration. Its manifest (and optional native lock) is validated only in the server-materialized worktree; it enables doctor --remote readiness inspection and explicit bootstrap --host-tools, never implicit provisioning.
run_profiles Named, opt-in profile definitions for mship run. A profile names a configured backend, non-empty eligible host roles (each declared in workspace run_hosts), optional host tags, and JSON-compatible backend options. When a selected repo declares profiles, bare mship run uses default_run_profile or, in an interactive TTY, asks you to choose.
run_backends Project backend-name map. A value with builtin: android\|flutter\|ios\|browser\|platformio selects a packaged adapter; optional discover_task and operations override only named inherited actions. Without builtin, retain the custom discover_task/operations/session_owner task form. See Run backends.
default_run_profile Optional configured profile name, which must name an entry in run_profiles. It is the default for that repo's bare, task-bound mship run; without a default, a TTY chooser is used or a non-interactive run reports that --profile is required.
repos:
  schemas:
    path: ../schemas
    type: library
    not_applicable: [run]          # this repo has no `run` task
    tags: [generated]
    base_branch: main
    expected_branch: main
    allow_dirty: false
    allow_extra_worktrees: false
    url: https://github.com/other-org/schemas   # overrides default_remote for bootstrap
    symlink_dirs: [.github]        # symlinked into each worktree from source
    bind_files: [".env.example", "config/*.toml"]   # copied into each worktree

  ground-control:
    path: ground-control
    type: service
    run_host: android-emu-host     # `mship build/capture --remote` targets this role
    setup_inputs: [build.gradle, gradle/libs.versions.toml]   # remote runs re-run `task setup` when these change
    capture:
      platforms: [android, ios]    # `mship capture --platform android|ios`
    host_tools:
      mise:
        manifest: .mise.toml
        lock: mise.lock
      requirements:
        - {id: android-sdk, kind: sdk}
        - {id: android-adb, kind: tool}

When the native mise.lock references a dependency graph, sidecars may be declared only as digest-pinned regular files. A lock entry may use either {path = "uv.lock", digest = "sha256:..."} or the bounded directory form {directory = ".aube", files = {"graph.json" = "sha256:..."}}. Every listed file must stay beneath the materialized worktree, be non-symlinked, and match its digest; at most 64 files per directory, 128 files total, and 1 MiB of sidecar bytes are admitted. The directory itself is not recursively trusted.

Profile and backend configuration

run_profiles is an executable, opt-in configuration surface: it selects a reviewed backend, eligible run-host roles, and backend options. It requires a resolved task. A run can select more than one repository: every selected profiled repository is discovered and preflighted before any app launches, dependency readiness boundaries are retained, and each launched repository receives its own recorded run ID. Repositories with no profiles retain the ordinary mship run behavior.

Profiles and backends are strict configuration objects: unknown nested fields, an unknown backend, an empty host-role list, a role outside run_hosts, or an override task key absent from tasks: rejects configuration. A pure builtin does not require tasks:; a builtin override names only its replacement actions and inherits the rest.

The run-target configuration example shows builtin-only, builtin-plus-override, and custom task-routing modes. Its Flutter extension Taskfile and custom-routing Taskfile delegate to the installed runtime rather than copying adapter source.

Keep tool paths, target aliases, device identities, credentials, app templates, and other machine-specific values in the owner-private $XDG_CONFIG_HOME/mothership/run-target-bindings.yaml (or ~/.config/mothership/run-target-bindings.yaml), never in mothership.yaml. Discovery is read-only and never installs an SDK, creates an emulator, pairs a device, provisions a target, or falls back to an ambient target. SDKs, tools, and app/simulator state required by a profile must be prepared on the selected host first. host_tools can diagnose or explicitly install its declared mise tools; it does not provision platform SDK components or targets.

Immutable declared task outputs

An exact logical task can opt into immutable generic result publication with task_outputs:. The key must be an existing key from that repository's tasks: mapping; it is never treated as a literal Taskfile target.

repos:
  reports:
    path: reports
    type: service
    tasks:
      publish-report: report
    task_outputs:
      publish-report:
        retention_seconds: 86400
        artifacts:
          - name: report
            relative_path: out/report.txt
            media_type: text/plain
          - name: archive
            relative_path: out/report.zip
            media_type: application/zip

Every artifact is an exact relative POSIX file path, not a directory, glob, or discovery rule. Names and paths are unique; media types are concrete; nested declaration fields are strict. The server supplies MSHIP_OUTPUT_DIR, MSHIP_OUTPUT_DECLARATION_FILE, and MSHIP_OUTPUT_MANIFEST; a producer writes only the declared files below the output directory and an exact ordered manifest.json projection. It cannot choose result IDs, output locations, retention, host provenance, or a different media type.

required defaults to true; set it to false only for an explicitly optional artifact. A successful producer missing a required artifact returns evidence_error with its persisted result_id; its immutable producing outcome still records the successful process exit. Missing optional outputs remain unavailable without changing that terminal status. Failed/cancelled tasks expose only complete outputs explicitly marked diagnostic_on_failure: true.

retention_seconds expires retrieval rights while retaining result metadata. Owner startup performs a bounded byte-retention sweep; expiry is enforced during retrieval even before that sweep. Producer metadata currently permits only an empty object. No arbitrary producer metadata or private environment is published.