Mash

Mash is a self-hosted durable runtime for code-authored automations using workflows with agents. A workflow is an ordered pipeline of typed steps, a step is deterministic Python or one run of a harnessed agent, and control flow stays in code.

Mash gives you a Python AgentSpec contract for defining agents, a WorkflowSpec for authoring step pipelines, a HostBuilder that composes both into a deployable pool, a FastAPI server for deployment, and a CLI/API for interacting with a running host.

It's designed around Host-to-Agent Protocol (H2A) that standardizes interactions between user applications and agents.

What Mash Provides

• Workflows: ordered pipelines of typed steps, durable and observable. A step is deterministic Python or one agent run; each step's output threads into the next step's input with schema checks at every edge. The pipeline is code you can read, diff, test, and replay.
• Agent harness: the agent loop runs inside a durable request engine with tools, skills, memory, and structured output. Requests are recorded as replayable runtime events; retries, restarts, and long-running work just work.
• Frontier and open-source models: built-in adapters for Anthropic, OpenAI, and Gemini, and any open-source model served over a Chat Completions endpoint, self-hosted with vLLM or Ollama or hosted on OpenRouter. Each agent picks its model in one line of build_llm().
• Self-hosted interfaces: HTTP API with streaming, CLI, and interactive REPL, all on one Postgres. Deploy locally, in Docker, or on any cloud.
• Multi-agent composition: define a primary agent, add specialized subagents, and compose workflows behind a single host. Agents delegate to each other without a separate coordination layer.
• Human-in-the-loop: agents can pause for approval or ask users questions mid-execution. Interactions survive host restarts.
• Observability: span trees, trace analysis, telemetry API, built-in dashboard, and CLI trace inspection. No external APM needed.
• Synthetic evals: generate a test dataset and scoring rubric from a host's declared capabilities, run experiments that snapshot the live host, and compare quality and cost across runs before the first user message. Datasets, rubrics, and experiment results live in the built-in dashboard.

                  ┌─────────────────────────────────────────┐
                  │          Durable Request                │
                  │                                         │
                  │   ┌─ context ─── memory ──┐             │
                  │   │                       │             │
request ────────► │   │     Agent Loop        │ ──► signals │
(cli/api)         │   │ think → act → observe │      │      │
                  │   │                       │      ▼      │
                  │   └─ tools ───── skills ──┘  structured │
workflow step ──► │        ▲                      output    │
(api/cli)         │        │ user interaction               │
                  │        ▼ (approval / ask-user)          │
                  │                                         │
                  │       resumable · replayable            │
                  └─────────────────────────────────────────┘

A request from a user and a step in a workflow ride the same durable loop.

See Mash under the hood for a deeper look at each capability, and the product brief for the pitch.

Quick Start

Install:

# install the library
uv add mashpy

# install the `mash` CLI on your PATH
uv tool install mashpy 

Define your agents:

Each agent is an AgentSpec subclass. It names itself, picks an LLM, and declares a system prompt, tools, skills and agent config.

## my_app/agents.py

from mash import AgentSpec
from mash.core.config import AgentConfig
from mash.core.llm import AnthropicProvider
from mash.skills import SkillRegistry
from mash.tools import ToolRegistry


class ConciergeAgent(AgentSpec):
    def get_agent_id(self):
        return "concierge"

    def build_tools(self):
        return ToolRegistry()

    def build_skills(self):
        return SkillRegistry()

    def build_llm(self):
        return AnthropicProvider(app_id="concierge")

    def build_agent_config(self):
        return AgentConfig(
            app_id="concierge",
            system_prompt=(
                "You are the concierge. Answer the user directly, and "
                "delegate research-heavy questions to the research subagent."
            ),
        )


class ResearchAgent(AgentSpec):
    def get_agent_id(self):
        return "research"

    def build_tools(self):
        return ToolRegistry()

    def build_skills(self):
        return SkillRegistry()

    def build_llm(self):
        return AnthropicProvider(app_id="research")

    def build_agent_config(self):
        return AgentConfig(
            app_id="research",
            system_prompt="You handle research-heavy questions in depth.",
        )

Author the workflow:

The workflow is the automation: an ordered pipeline of typed steps that code owns end to end. Use a CodeStep for deterministic Python and an AgentStep when the work needs an agent.

## my_app/workflows.py

from pydantic import BaseModel

from mash import AgentStep, CodeStep, StepContext, WorkflowSpec


class ResearchRequest(BaseModel):
    topic: str


class ResearchPlan(BaseModel):
    topic: str
    questions: list[str]


class ResearchBrief(BaseModel):
    summary: str
    sources: list[str]


def plan_research(
    request: ResearchRequest,
    _context: StepContext,
) -> ResearchPlan:
    return ResearchPlan(
        topic=request.topic,
        questions=[
            f"What are the key facts about {request.topic}?",
            f"What should a reader understand about {request.topic}?",
        ],
    )


RESEARCH_BRIEF = WorkflowSpec(
    workflow_id="research-brief",
    input_model=ResearchRequest,
    steps=[
        CodeStep(
            step_id="plan",
            run=plan_research,
            input=ResearchRequest,
            output=ResearchPlan,
        ),
        AgentStep(
            step_id="research",
            agent_id="research",
            input=ResearchPlan,
            output=ResearchBrief,
        ),
    ],
)

The CodeStep output becomes the AgentStep input. Mash validates both edges, runs each step durably, and uses the last step's output as the workflow result.

Build the pool:

The pool is the unit of deploy: agents and workflows registered together.

## my_app/host.py

from mash import AgentMetadata, HostBuilder

from .agents import ConciergeAgent, ResearchAgent
from .workflows import RESEARCH_BRIEF


def build_pool():
    pool = (
        HostBuilder()
        .agent(
            ConciergeAgent(),
            metadata=AgentMetadata(
                display_name="Concierge",
                description="Front-door agent that answers users and delegates.",
                capabilities=["conversation", "delegation"],
                usage_guidance="Default entry point for user requests.",
            ),
        )
        .agent(
            ResearchAgent(),
            metadata=AgentMetadata(
                display_name="Research",
                description="Handles research-heavy questions in depth.",
                capabilities=["research", "analysis"],
                usage_guidance="Use for questions that need digging.",
            ),
        )
        .workflow(RESEARCH_BRIEF)
        .build()
    )
    return pool

A pool can also be workflows alone. A workflow of pure CodeSteps references no agents, and the resulting pool serves only workflow runs:

def build_pool():
    # EXPORT_METRICS is a WorkflowSpec of pure CodeSteps; no agents needed.
    return HostBuilder().workflow(EXPORT_METRICS).build()

Configure the environment:

The host needs an LLM key and a Postgres URL for its durable runtime. Put them in a .env file the host loads on start:

# .env
ANTHROPIC_API_KEY=sk-ant-...
MASH_DATABASE_URL=postgresql://user:pass@localhost:5432/mash

Start the host:

mash host serve --host-app my_app.host:build_pool --host 127.0.0.1 --port 8000

Browse available agents:

mash browse

Compose an assistant host with primary and subagents:

mash compose --host assistant --primary concierge --subagents research \
  --workflows research-brief

Talk to the host or execute / commands using Mash repl:

mash repl --host assistant

Key Concepts

Mash Pilot

Pilot is a command-line guide to the Mash codebase, built on the Mash SDK and shipped in this repo at src/pilot/. Its agents specialize in Mash's own modules — so instead of reading docs or grepping the source, you ask Pilot and it answers from the actual source tree.

> Summarize how HostBuilder registers pooled agents and host compositions.
> Trace how an accepted request moves through AgentRuntime and RequestEngine.
> When is request.waiting emitted, and what does it mean for a busy session?

Quick start:

# 1. Start the host — one container, embedded Postgres, Mash source included
docker run -d --name pilot -p 8000:8000 \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -v pilot-data:/var/lib/pilot \
  ghcr.io/imsid/mashpy-pilot:latest

# 2. Install the CLI and ask
curl -fsSL https://raw.githubusercontent.com/imsid/mashpy/main/install.sh | sh
pilot repl --host guide

Add -e GITHUB_MCP_PAT=ghp_... to enable the guide's commit-inspection tools. The pilot-data volume keeps the database durable across restarts.

The guide team — one agent per module:

Scaffolding your own app: the guide carries build-mash-agent, build-mash-workflow, and build-mash-host skills so it goes beyond explaining Mash to scaffolding your application:

> Build me a support agent with a knowledge base search tool and human approval for refunds.
> Scaffold a multi-agent code reviewer with separate agents for security, style, and correctness.
> I need an agent that connects to my MCP server at localhost:3000 and uses Gemini.

Use pilot serve from a source install to run your own host, or point the CLI at any Mash deployment with --api-base-url. See src/pilot/ as a reference when structuring your own multi-agent app.

Build with a Coding Agent

This repo includes CLAUDE.md so coding agents like Claude Code, Codex, and Cursor can scaffold a Mash-powered agent from a natural language prompt. Copy it into your project or point your agent at this repo to get started. The Pilot guide (above) also carries the build-mash-agent, build-mash-workflow, and build-mash-host skills for interactive scaffolding from the REPL.

Documentation

• Product brief — the pitch: why the application-to-agent seam needs a standard
• Mash under the hood — what Mash offers and where it fits
• Synthetic evals — datasets, rubrics, experiments, and scoring for the cold-start problem
• Deployment guide — Docker, cloud, horizontal scaling
• Building agent CLIs — custom CLI development
• CLAUDE.md — full SDK reference for coding agents
• Package overview — subsystem boundaries and module guides
• Contributing — development setup, tests, repo structure

Contributing

Contributions are welcome. See CONTRIBUTING.md for setup, tests, and the pull request flow, and SECURITY.md for reporting vulnerabilities. Release notes live in CHANGELOG.md.

License

Mash is licensed under the Apache License 2.0.