Marea

Marea is an extensible CLI for the lifecycle of Elixir applications — building, packaging, running, deploying and operating them. It is plugin-based end-to-end: every command, every config field, every workflow comes from a Malla plugin, so the same binary covers local development, container builds, Helm + Kubernetes deploys, AWS plumbing, or whatever you wire in. The set bundled today (see What's in the box below) covers the workflows most Elixir projects need; adding a plugin of your own — a different registry, a custom deploy target, an extra build step — is typically a few-dozen-line module, not a fork.

Marea is also, by philosophy, a thin and transparent wrapper around the tools it drives. Every shell call is printed before it runs, making its actions completely visible. There is no hidden orchestrator, no cluster-side controller, no daemon, and no lock-in.

In production today. Marea currently powers the day-to-day deploy and operational workflow of a complex telemedicine project, with dozens of releases shipping across several Kubernetes environments and nearly daily deployments. The patterns documented here are the ones running on real clusters every day.

LLM-ready, MCP-native

Marea was designed with LLM coding agents (Claude Code, Cursor, …) in mind, and it works very well with them even without MCP. Every command is a short, standard CLI invocation (marea build docker, marea helm upgrade, marea run release) and every shell call Marea makes — mix, docker, helm, kubectl, aws — is printed before it runs and its output is captured in the session. An agent reading the transcript sees exactly what happened, learns the workflow from any guide or --help page, and can copy-paste-debug from real tool error messages just like a human operator. There is no proprietary DSL to teach the agent and no hidden framework state to infer.

Turn on MCP and it gets better — and under control.marea mcp serve exposes every leaf subcommand as a typed Model Context Protocol tool, with a JSON Schema auto-derived from the same plugin metadata that drives the CLI — so every plugin you load contributes tools for free. Destructive operations (helm delete, helm rollback, AWS deletes) are tagged with destructiveHint: true; read-only ones with readOnlyHint: true. The MCP client allowlists exactly the tools the agent may call, requires confirmation for the dangerous ones, and feeds typed arguments instead of free-form shell strings. The agent never has to escape its own sandbox to talk to AWS, Kubernetes or Docker — Marea runs outside that sandbox and does it on the agent's behalf, one typed tool call at a time. See the MCP Plugin guide.

What's in the box

Currently Marea bundles following plugins, convering:

Configuring, building and deploying complex Elixir application.
Targets can be local, docker or kubernetes/helm.
Tools availale for AWS.

Plugin	Description
base.md	The glue every other plugin hooks into. Adds global flags and a command to inspect your project's effective configuration.
setup.md	Scaffolds a new umbrella project and wires Marea into it, ready to build and deploy.
build.md	Builds Elixir releases locally — the standard `mix release` flow with the rough edges smoothed out. Plugins like docker and helm expands the build capabilities
run.md	Runs your system on your laptop, either straight from `mix` or as the same release that ships to production.
mcp.md	Exposes Marea's full command tree as a Model Context Protocol stdio server, so LLM agents (Claude Code, …) can drive builds, deploys, Helm and AWS operations through structured tool calls instead of shelling out. Auto-derives JSON Schema for every leaf command from the same plugin metadata that defines the CLI.
docker.md	Packages Elixir releases (or arbitrary Dockerfiles) into Docker images — small, reproducible, ready to push. See also docker/python to add a Python environment inside the release's Docker image, for projects that mix Elixir with Python tooling.
helm.md	Turns your project into a Helm chart, deploys it to Kubernetes, and manages upgrades, history and rollbacks.
k8s.md	Day-to-day operations against running pods: tail logs, open a shell, attach a remote IEx console, restart a deploy.
aws.md	Wraps the AWS bits most projects need: ECR registry login, Route53 DNS records, S3 bucket sync.

Highlights

Out of the box. Covers everything you need to deploy a modern, complex distributed application: configs, secrets, Erlang clustering, k8s templates, etc.
Fast time-to-production. Once set up, most changes-to-production cycles take 1-2 minutes. Marea uses a number of tricks to make deployments extremely easy, fast and convenient.
Extensible by design. Custom logic — extra commands, alternative build pipelines, additional cloud providers — is added via Malla plugins, no need to edit core code. Because every callback is a Malla chain, a plugin can also modify the built-in commands: intercept build docker to run a linter first, add a flag to helm upgrade, inject a field into another plugin's schema. Most customisations are a few-dozen-line plugin, not a fork. While Marea is based on Malla, your projects do not need to use Malla at all.
Commands are short, consistent and visible.marea build docker, marea helm upgrade, marea run release. Every shell call is printed before it runs, along with the command's output. That is heaven for LLM agents.
First-class LLM agent integration.marea mcp serve exposes every command as a typed Model Context Protocol tool, so Claude Code (or any MCP client) can drive Marea through structured tool calls — auto-derived JSON Schema, per-tool allowlisting, destructive operations gated with destructiveHint. The agent never has to bypass its sandbox to talk to AWS, Kubernetes or Docker: Marea does it on its behalf. See the MCP Plugin guide.
Umbrella-native. A single marea.yaml describes a whole project, whatever shape it has: a single BEAM with everything, a few releases grouping related apps, or one release per app. The same marea build / marea helm commands work on all three. For develop you launch all-as-one in your local machine, while you send specific releases to production.
EEx-driven templates. Both the Dockerfile that builds your images and the Kubernetes manifests that ship them are rendered through EEx. At expansion time you have full Elixir — pattern matching, comprehensions, file-driven config — and for Helm, EEx and Helm's own {{ .Values… }} coexist: EEx runs at marea helm chart, Helm runs at helm upgrade.
Not just Elixir. Releases can also be plain Docker images (type: dockerfile_dir) o full Helm packages for companion services like sidecars, migrations or auth proxies that ride along with your Elixir apps.
Operational tooling, not just deploys. Marea also helps you connect to running pods (via kubectl exec) for debugging and hot-fixes against a live release.
Self-contained binary or Mix tasks. Ships as a marea executable (an escript wrapped in a shell header), or can be used also as family of Mix tasks

Quick example

# marea.d/marea.yaml
plugins:
  - Marea.Plugins.Helm
  - Marea.Plugins.K8s
  - Marea.Plugins.Aws

aws:
  default:
    profile: my-aws-profile
    region: eu-west-1
    account_id: "123456789012"
    ecr:
      image_header: my-org/

deploys:
  staging:
    helm:
      namespace: my-app-staging
      kube_context: staging-cluster
    releases:
      api:
        type: elixir
        helm:
          template: deployment.yaml
        domains:
          - api.staging.example.com

mix marea aws ecr login-docker
mix marea build helm --deploy staging --release api --upgrade

A full walkthrough lives in guides/03-quick-start.md.

Documentation

The guides/ folder contains progressively numbered topic guides:

Guide	Description
01-introduction.md	What Marea is, the plugins it ships, and the design principles behind it.
02-installation.md	Building the binary, linking it into projects, scaffolding new umbrellas.
03-quick-start.md	A complete deploy from empty project to running pod.
04-marea-yaml.md	Full reference for the `marea.yaml` deploy file, including the `marea.d/` directory layout, YAML includes, and secret references.
05-architecture.md	How the plugin system, callback chains, and deferred shell execution actually work.
06-plugin-development.md	Write your own plugin: schema fields, CLI subcommands, command dispatch.
07-operations.md	Day-2 workflow: remote IEx console, hot-fixes, rollback.
08-commands.md	Top-level command tree, global flags, links to per-plugin command lists.

Per-plugin reference guides live in guides/plugins — see What's in the box above for the current list.

License

See the repository for current licensing terms.