Run Plugin

Execute the system locally, as a release, or inside a Docker container. Each marea run command ends with a deferred shell command that takes over the parent shell, so you get an interactive iex/bin/<release> session attached to your terminal.

Always loaded (part of @base_plugins).

These commands are exposed as MCP tools (run_local, run_release, run_docker), but they're inherently interactive — calling them through marea mcp serve captures their output rather than producing a real iex session. For day-to-day local development, use the CLI.

Commands

marea run
├── local     [--cookie <c>] [--pos <n>]
├── release   --deploy <d> --release <r> [--cookie <c>] [--pos <n>]
└── docker    --deploy <d> --release <r> [--cookie <c>] [--pos <n>]

Common options:

marea run local

Executes:

ENV=dev TARGET=local iex --name marea@127.0.0.1 --cookie "<cookie>" -S mix run

--pos n (with n > 0) renames the node to marea_n@127.0.0.1 so a second IEx session can run alongside the first.

The command is returned as {:cmd, cmd} and executed after the escript exits — that's why the resulting iex attaches to your terminal as a normal interactive session.

marea run release

Looks up the release with Lib.get_release!/1 and executes _build/prod/rel/<release>/bin/<release> start_iex with the right environment:

NODE_HOST=127.0.0.1 \
NODE_NAME=<release>[_<pos>] \
RELEASE_COOKIE=<cookie> \
MAREA_RELEASE=<release> \
MAREA_DEPLOY=<deploy> \
MAREA_SYSTEM_PORT=<3001+pos> \
_build/prod/rel/<release>/bin/<release> start_iex

--pos n lets you start multiple nodes of the same release on the same host with different node names and HTTP ports.

marea run docker

Runs the most recently built Docker image for the release:

docker run -ti --rm \
  -e MAREA_RELEASE=<release> -e MAREA_DEPLOY=<deploy> -e NK_SYSTEM_PORT=0 \
  --hostname <node> --name <node> --platform arm64 \
  <release>:<image-tag>

The image tag comes from last_values.git_vsn (from a previous build docker / build helm), or latest if none. A summary table is printed before the deferred command is executed:

If you've built with a non-arm64 platform, edit the --platform argument in run.ex or pass --platform to build docker so the image matches the host you intend to run on.

How the deferred shell trick works

All three commands return {:cmd, cmd} from Marea.Plugins.Base.marea_cmd/2, which:

• when running the binary, writes cmd to .marea/next_cmd, and the shell wrapper around the escript execs that file after the BEAM exits;
• when running via mix marea …, is short-circuited to {:exec, cmd} and executed via a Port with stdio forwarded interactively.

See 05-architecture.md for the underlying mechanism.

Source

• lib/marea/plugins/run.ex