Skip to content

Run & observe

When you need this: you (or your agent) need the system actually running to see a change work — not just unit tests passing.

Bring the stack up

Profile-free services

The ordinary service workflow is unchanged:

mship run --repos api,svc-users
mship logs api
mship capture --repo web --platform browser

run starts the selected services in dependency order, waiting on each repo's healthcheck before starting its dependents — tcp, http, sleep, or a custom task, declared per repo in mothership.yaml (Configuration). Long-running services (start_mode: background) stay alive so you can interact with them. Ports and URLs are task-scoped: two tasks running in parallel don't fight over localhost:3000.

Profile-aware app sessions (opt-in)

When a task-bound repo declares run_profiles, the same run --repos command opens a selected app session rather than changing to a separate command:

# Run this from the task worktree, or supply --task <task>.
mship run --repos app
# app: run <run-id> is ready

# Observe the acknowledged session that run established.
mship logs app --run-id <run-id>
mship capture --repo app --run-id <run-id> --kind image

For a configured repo, bare run uses its default_run_profile. Without a default, an interactive terminal offers the configured profiles; a headless call must name --profile. --host and --target constrain launch selection. Mship resolves and preflights every selected profile before launching an app, retains dependency-ready boundaries, and records one run ID per selected repo.

The run ID is an observation identity, not another device selector. logs and capture use it to contact the exact recorded owner on its recorded host; they do not rediscover a target, transfer source, run setup, relaunch the app, or silently substitute a different session. If an active task/repo has exactly one acknowledged matching run, mship logs app and mship capture --repo app reuse it without --run-id. Several matches prompt in a TTY and otherwise require --run-id; a missing, stale, inactive, or uncertain run must be replaced with a new mship run, not recovered by an observation command.

--profile, --host, and --target on logs or capture filter recorded runs. When combined with --run-id, every filter must agree with that record; contradictions fail rather than selecting something else. The capture platform is inferred from the recorded session. Supplying --platform only validates that it agrees; --kind image|layout|all chooses the artifact(s), not a platform, device, or session.

Profiles are opt-in, configured wrappers. They do not adopt an app started outside mship, install tools or SDK components, create emulators, pair devices, or provision targets. A repo may select a packaged run_backends builtin without a project Taskfile; configuration chooses android, flutter, ios, browser, or platformio, while the selected host supplies the external SDK, browser driver, or board tooling.

Projects can override only policy-specific discovery or operation tasks. Every omitted action continues to use the builtin. Such a task delegates with "{{.MSHIP_SESSION_PYTHON}}" -I -m mship.backends <builtin> [discover]; for regular operations it supplies no caller-selected action or target arguments. Mship provides sealed request, selected-context, and host-binding files, and the helper must consume them instead of synthesizing a new context.

Android and Flutter retain their native session ownership. An override may add project policy, but it must not replace the framework owner, retarget an existing session, or create a parallel process/device session. Browser, PlatformIO, and iOS prerequisites remain external and target-specific: an unavailable engine/driver, board, serial permission, or Apple tooling is an actionable readiness failure, never a silent fallback. Native physical iOS operations remain unsupported pending a concrete owner.

The run-target configuration example shows builtin-only, builtin-plus-override, and custom task-routing modes. For the full configuration schema, see Configuration; for selected-host and remote-session behavior, see Profile-aware runs and observations.

Build artifacts

mship build

Same dependency ordering, running each repo's build target — schemas generate before the services that import them compile.

See what's real

The observation commands answer questions agents otherwise guess at:

mship status      # active task, phase, branch, per-repo test results, drift
mship context     # full JSON snapshot of workspace state (built for agents)
mship journal     # the task's log: what was done, when, why
mship graph       # the repo dependency graph
mship worktrees   # every active worktree, grouped by task

All of these emit JSON when stdout isn't a TTY (or with mship --json …), so an agent gets structured answers — which log belongs to which service, which URL to hit, which test command runs where — without find/ps/lsof archaeology.

Capturing what's on screen

For UI repos without a selected profile session, mship capture --repo <repo> drives that repo's capture target (simulator screenshots, layout dumps) and files artifacts under .mothership/captures/<task>/.

Promoting a capture to evidence

Most captures are part of the develop–verify–iterate loop: screenshot, look, adjust, capture again. Those stay ephemeral — mship capture writes them under .mothership/captures/, which is gitignored, and nothing else happens.

Passing --evidence <spec-id>:<criterion-id> promotes a capture into durable evidence for that acceptance criterion:

mship capture --repo app --evidence my-spec:ac3

The artifact is copied into .mothership/evidence/<spec-id>/ under a content-hashed name, attached to the criterion as kind=artifact, and recorded with the revision it was taken from — marked when that revision is an uncommitted working tree, and separately marked when the revision itself is not a commit on any branch (a detached HEAD, or a throwaway ref materialized for a remote capture), so a reviewer can tell work-in-progress or throwaway evidence from a screenshot taken at a real, committed revision. Both markers can appear together.

The store is machine-local and gitignored, so it behaves identically whether your workspace is a metarepo, a monorepo, or a single repo — nothing is ever committed into your product's history by capturing evidence.

Artifacts are capped at 8 MiB each — a phone fetches these over the relay, and a screenshot or layout dump larger than that is a capture bug, not evidence. An over-cap artifact is refused when it is stored (the capture itself still succeeds) and refused again if one ever reaches the store another way.

What travels: the phone fetches evidence from mship serve over the relay. The PR body embeds it when the bytes are fetchable on GitHub, which means evidence_storage: published and the bytes actually on a ref GitHub serves. You do not have to arrange that second half: under published storage mship finish publishes the referenced artifacts to an mship-evidence orphan branch in the repo the pull request targets, and embeds a raw URL pinned to that branch's commit.

An orphan branch shares no history with your default branch, so the binaries never enter main's tree and a clone of the product is unaffected. finish pushes that branch and nothing else — never main, never your workspace repo — and when a task spans several repos, each repo that gets a PR publishes to its own branch, so every PR is self-contained. Published artifacts accumulate on the branch; nothing prunes them for you.

The publication is built with git plumbing, not a checkout, so your working tree, index, HEAD and branches are untouched: work you have in flight — untracked, edited, or already staged — cannot be swept into it. Nothing is forced: a rejected push, an unreachable origin, or a repo with no GitHub origin all stop the publish rather than push past it.

Every failure there degrades and none of them block the PR: finish warns, names the artifact instead of embedding it, and carries on opening the PR. It also warns under local or encrypted storage, where the bytes are not on GitHub in readable form at all and nothing is published.

What does not travel: secrets, platform state, and anything else git cannot carry.

Running on another machine

A legacy run or capture target that needs hardware you do not have (an iOS simulator on a Mac, an Android box, or a beefier builder) can use a configured run host:

# Requires an active task (or pass --task <task>).
mship run --remote=ios-sim-host

The host must already be configured and ready; mship does not provision its tools or devices. A selected profile capture remains an observation of the recorded owner: it performs no source transfer, setup, launch replacement, or target rediscovery. Setup, host selection, recovery, and the distinction between legacy remote execution and selected-session observation are covered in Profile-aware runs and observations.