#NAME

marsh, msh - shell for composing agents

#SYNOPSIS

marsh [--shell bash|zsh|marsh] [--load KIT[,KIT...]|all] [--ephemeral-home] [--dev] [SHELL_ARGS...]

marsh COMMAND [ARGS...]

msh ...

#DESCRIPTION

marsh opens a Linux shell for the current directory on an Apple Silicon Mac. The shell is a patched Brush, a Bash-compatible shell, running in a Docker Sandbox VM created with the stock sbx command. The project directory is mounted read/write at its exact Mac path, so pwd prints the same path inside and outside.

Some command names are registered. By default these are claude, codex, pi and shell. Each registered command runs as a fresh, nonroot container from its Kit image, in a warm VM kept for that Kit. The container is deleted when the command ends.

Registered commands work in pipelines, scripts, make, and background jobs like any other command. A registered command started from inside another one becomes its child job.

split runs commands in parallel on private copies of the project. join prints each branch's output and patch. Registered commands in a split mount only their fork; use join --keep to retain patches for inspection and application. A shell branch's own code (-b) is not confined to its fork. fanout runs branches on shared files, and collect prints their output in declaration order.

Direct jobs can change or delete project files. Jobs using the same guest home can read one another's settings, history, and saved logins. Keep the project in Git, and use split for agent changes you want to review first. See https://runmar.sh/docs/security.html.

msh is a symbolic link to marsh and behaves identically.

With no COMMAND, marsh starts the shell. Arguments it does not recognize go to the shell, so marsh -c 'command' and marsh script work as they do with Bash. After -c or --, marsh interprets nothing.

#OPTIONS

--shell bash|zsh|marsh

Run the shell VM's GNU Bash or zsh, with your own startup files, instead of Brush (marsh, the default). Registered commands and the marsh CLI work in all three.

--load KIT[,KIT...]|all

Prepare the named Kit VMs before the prompt appears. Otherwise the first call to a Kit boots its VM and prints [starting NAME worker VM…].

--ephemeral-home

Use a blank, private guest home that is not kept after the shell exits. If it cannot be released, the slot is retained; see recover-home.

--dev

Open a development shell whose sbx is a scoped host broker. Its grant belongs to the shell, not Kit jobs. For developing marsh itself; requires a development-enabled install or daemon.

-h, --help

Print a summary of commands and exit.

-V, --version

Print the version and exit.

#COMMANDS

status [--json]

Show the daemon, its host control directory, per-job limits, shells, and Kit workers.

jobs [--all] [--tree] [--json]

List Kit jobs, running first, then newest. --tree draws children under their parent. In a shell, only that session's jobs; from a host terminal, running trees, trees from the last hour, and the five newest. --all lists every recorded job. --json omits the session/recent-jobs filter. Inside a job, all forms remain limited to that job's subtree.

jobs show JOB [--json]

Show one job. JOB may be an id prefix.

run [--spawn NAME,...|--no-spawn] NAME [ARG...]

Run registered command NAME as a new job. Inside a job it is a child job. --spawn and --no-spawn narrow what NAME may start in turn.

context

Print the text every job is given about marsh (its name, limits, and how to start other jobs).

results [--json]

List finished jobs, newest first: command, exit status, cleanup, timing. WALL is the whole request, from the call to verified cleanup. It includes any Kit VM boot. jobs shows RUN, the job's own run in the ready VM.

results show CURSOR|JOB [--json]

Show one finished job.

split [-n] [-b LABEL=STRING]... [::: LABEL CMD [ARG...]]...

Run each branch at once in its own private copy of the current directory and wait for all of them. -b runs STRING with the shell in the shell VM; ::: runs one registered command in a container that sees only its copy. -n gives branches empty stdin. Prints one handle line, which join reads on stdin.

join [--json] [--keep] [--timing] [-- CMD [ARG...]]

Read a split handle on stdin and print each branch's status, output, and patch. Only the split's creator can join it. --keep retains the split and its patches, even on success; without it, success removes them. --json prints the manifest instead of the text rendering. --timing prints phase timings to stderr. With -- CMD, run CMD on that output with SPLIT_ID, SPLIT_DIR, SPLIT_MANIFEST and SPLIT_OBJECTS set; the split is removed if CMD exits 0, unless --keep is set, and kept otherwise. CMD runs even if a branch failed, and join returns its status. Without CMD, join returns the first nonzero branch status. CMD runs in the caller's environment: on the Mac, in the shell VM, or in the job container where marsh join was invoked.

splits [--json] [ID]

List splits. With ID, show its state and phase timings, even after joining.

splits cancel ID

Cancel a running split.

splits rm ID

Remove a kept split and its patches.

fanout [-n] [-b LABEL=STRING]... [::: LABEL CMD [ARG...]]... | collect [--json] [--timing] [--stderr]

Run branches at once on the same files (no copies). Print each branch's output in declaration order: its header, its stdout, then a failed branch's stderr. --stderr prints every branch's stderr. collect exits with the first nonzero branch status. Limits: 16 branches, 64 MiB of input, 16 MiB of combined branch output.

config shell [bash|zsh|marsh]

Set, or with no name print, the default shell for this MARSH_HOME.

kit install NAME --from REPOSITORY@sha256:DIGEST

Register a published Kit under NAME in this scope.

workers reset KIT[,KIT...]|all

Remove idle Kit VMs, including quarantined ones. The next use creates a new VM.

reset [--json]

Remove every VM this scope owns. The daemon keeps running. Refuses while shells or jobs are active. The guest home and results are kept. Exits nonzero if any cleanup could not be verified.

stop [--json]

Remove every VM this scope owns and stop its daemon. Refuses while shells or jobs are active. The guest home and results are kept. Exits nonzero if any cleanup could not be verified.

recover-home SLOT --discard

Discard a retained --ephemeral-home slot (0 to 15).

mcp install codex|claude|sbx

Register marsh as an MCP server for this project. codex and claude launch it on demand; sbx gives selected sandboxes a shared per-project host broker. Run this on the Mac. The server uses a separate managed scope root rather than the CLI's default home.

mcp install-published codex NAME, mcp remove-published codex NAME

Register or remove a published pipeline as a tool for host Codex. Only codex is supported. Run on the Mac from the publishing project with the same MARSH_HOME. Removing the registration does not revoke the publication.

mcp serve [MCP_OPTIONS...]

Serve MCP over stdio from a host process. Without --scope-root or --home, use the CLI's selected home and disable creation of managed scopes.

mcp export-serve [MCP_OPTIONS...] --declaration PATH

Serve only the tool in a publication declaration. Requires --home.

mcp start, mcp stop

Start or stop the project's host MCP broker. stop refuses while a sandbox is attached.

mcp load NAME --sandbox SANDBOX

Load an existing publication into a running same-user sandbox. Does not replace the publication or invalidate other clients.

mcp unpublish NAME

Revoke a publication, including calls from clients that already loaded it.

acp install-published codex NAME, acp remove-published codex NAME

Register or remove a published ACP control tool with host Codex. Only codex is supported. Run on the Mac from the publishing project with the same MARSH_HOME.

help [COMMAND]

Show general help or help for a host command that has a help section.

#MCP SERVER OPTIONS

--workspace PATH

Manage this project directory. Defaults to the current directory.

--scope-root PATH

Use a private root for separate managed scopes.

--home PATH

Use one MARSH_HOME, with managed-scope creation disabled. Cannot be combined with --scope-root.

--marsh PATH, --sbx PATH

Select the installed marsh and stock Docker Sandboxes executables.

--allow-full-sbx-control

Enable fixed repository qualification gates on the Mac. These execute the project's Makefile; use only with a trusted checkout. Does not enable a generic host-command tool.

#SHELL COMMANDS

Inside the shell, these commands are also available:

ps --marsh [--verbose|--json], top --marsh [--verbose] [--once]

Show this project's shell, Kit jobs, and ACP sessions. top --marsh cannot show CPU or memory.

acp reserve AGENT

Reserve a session ID for this shell and print it. Start the session within 15 seconds or reserve again.

acp run [--reservation ID] AGENT &

Start an agent session as a background Kit job. Print its session and job IDs to stderr when ready.

acp list [--mine] [--wait [ID]] [--json]

List this project's sessions. --mine selects those this shell started. --wait waits at most four minutes for readiness; without an ID it requires exactly one live session. Use a reserved ID to wait for a new one.

acp ask ID TEXT

Send a prompt and print the answer. A sole - reads UTF-8 stdin. Text and its encoded control messages must each fit 1 MiB. After an uncertain failure, inspect acp status before retrying through acp prompt --key with the reported key and identical text.

acp prompt [--key UUID] ID TEXT

Submit a prompt without waiting for the answer; - reads stdin as for ask. Use status to read updates. Reuse a key only with identical text.

acp status ID [CURSOR] [--json]

Show state, agent updates, and pending permissions. Pass the JSON reply's next_cursor back unchanged to read only newer updates.

acp permissions ID [--json]

List requests awaiting one-time approval and the options for answering them.

acp respond ID REQUEST OPTION

Answer a pending permission request with one of its offered options.

acp cancel ID

Cancel the current turn without stopping the session.

acp attach ID, acp release ID

Take control of an unowned session or release this shell's control.

acp stop ID

Stop the session and its Kit job.

acp publish ID --name NAME [--kit KIT|--sandbox SANDBOX]

Publish an idle session as an MCP control tool. Callers can prompt, cancel, and answer one-time permissions. With a target, load it there immediately; start a new client agent session to discover it.

acp unpublish NAME

Revoke the control tool. Unpublish before steering the agent from its shell.

ACP usage errors exit 2. Other failures print acp: MESSAGE and exit 125. See https://runmar.sh/docs/acp.html.

mcp publish NAME [--description TEXT] [--kit KIT|--sandbox SANDBOX] -- 'PIPELINE'

Publish a fixed pipeline as an MCP tool. With --kit or --sandbox it is loaded there now. With neither, every agent Kit VM created from now on loads it before its first job. Kit VMs already running are not changed; use mcp load NAME --kit KIT to load into one now.

mcp load NAME --kit KIT|--sandbox SANDBOX

Load an existing publication into the named Kit VM or running sandbox.

mcp unpublish NAME

Revoke the tool everywhere it was loaded.

split { label: commands ... } | join [--keep] [| CMD], fanout { ... } | collect

Brush forms of split and fanout.

#ENVIRONMENT

MARSH_HOME

Absolute path of the scope root. The guest home is $MARSH_HOME/home. Default ~/.marsh.

MARSH_SHELL

The shell to run (bash, zsh, or marsh). --shell overrides it.

MARSH_SBX

Path to the stock sbx executable. Default: sbx on PATH. If there is none, install Docker Sandboxes with brew install docker/tap/sbx, then run sbx login.

MARSH_SPAWN

Comma-separated registered names that jobs started from this shell may start, or none. A job cannot widen the list.

MARSH_CONTROL_HOME

Host-only state root: scope control directories and MCP/ACP publications live under it. Default: control directories in ~/Library/Application Support/marsh/control, publications in ~/Library/Application Support/marsh.

MARSH_JOB_CPU_MILLIS, MARSH_JOB_MEMORY_BYTES, MARSH_JOB_PIDS, MARSH_JOB_WRITABLE_BYTES, MARSH_JOB_OUTPUT_BYTES, MARSH_JOB_WALL_SECONDS, MARSH_TREE_KIT_VMS

Per-job limits, read when the daemon starts.

MARSH_PLACE

Placement for registered commands. Only local is accepted.

#FILES

$MARSH_HOME/home (default ~/.marsh/home)

Backing store for the guest home.

$MARSH_HOME/config.json (default ~/.marsh/config.json)

The default shell set by marsh config shell.

$MARSH_HOME/sbxenv.yaml, $MARSH_HOME/sbxenvs/NAME.yaml

Optional shared and per-command MCP servers and extra directories. Read at daemon startup; changes require marsh stop and a new launch. See https://runmar.sh/docs/configuration.html#servers-and-extra-directories.

~/Library/Application Support/marsh/control/HASH/

Host-only control directory for a scope: commands.json, agents.json, the results journal. marsh status prints its path.

PREFIX/libexec/marsh/

Linux guest binaries, the packaged command registry, and the shell image reference.

.marsh/split/ID/out/

Results of a split, inside the project.

#EXIT STATUS

As for Bash, with these additions:

0-255

Registered commands return the container's exit status.

125

A job start was refused. The reason is on stderr. acp failures also exit 125.

126

A registered-name link was refused because MARSH_SPAWN excludes the name. marsh run returns 125 for the same refusal.

130

The job was interrupted.

#EXAMPLES

Start a shell in a project:

cd ~/src/project && marsh

Ask two agents for independent fixes in private copies and look at both:

marsh split -n ::: a claude -p 'fix the flaky test' \
               ::: b pi -p 'fix the flaky test' | marsh join --keep

join prints, for each branch, a header, its output, and a line giving the files changed and the path of its diff.patch. --keep retains the patches for inspection and git apply; a successful bare join removes them. After applying a patch, remove the retained split with marsh splits rm ID. Sample output: https://runmar.sh/docs/split.html.

Talk to one agent across turns, inside the shell:

id=$(acp reserve pi-session)
acp run --reservation "$id" pi-session &
acp list --mine --wait "$id"
acp ask "$id" 'What project files can you see? Do not change files.'
acp ask "$id" 'Which of those describe how to run the tests? Do not change files.'
acp stop "$id"

Run tests and lint at once:

marsh fanout -n -b test='make test' -b lint='make lint' | marsh collect

Publish a pipeline in the shell, then give it to Codex on the Mac:

mcp publish lint -- 'make lint 2>&1'

From a Mac terminal in the same project and MARSH_HOME:

marsh mcp install-published codex lint

#SEE ALSO

sbx(1), bash(1)

Documentation: https://runmar.sh/docs/ (start with https://runmar.sh/docs/quickstart.html; limits and trust in https://runmar.sh/docs/security.html)

#HISTORY

marsh began life as the mark shell.

#BUGS

Report bugs at https://github.com/mcavage/marsh/issues.