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.