Concepts

This page explains the building blocks of muthr. The rest of the docs assume familiarity.

The three planes

muthr manages three independent runtime planes. Each has its own lifecycle and CLI namespace.

Engine plane

Inference backends run on the host. muthr starts, stops, and queries them with muthr engine. Supported runtimes:

• llama-server: llama.cpp server
• mlxcel-server: Apple MLX-based inference
• vllm-mlx: vLLM with MLX backend

The engine serves an OpenAI-compatible API. Sandboxes and services connect to it over the network.

Services plane

A persistent layer that agents depend on during runtime. Managed with muthr services:

• muthr-services: MCP bridge and routing
• muthr-searxng: search tooling

These containers stay running across sandbox sessions.

Sandbox plane

Per-project containers managed with muthr sandbox. One container per project directory. Sandboxes get destroyed and recreated; they are not long-lived resources.

Why sandbox, not just containers

Running an AI agent on the host means it executes package installers, shell commands, and network requests with full filesystem access. A compromised dependency or a prompt-induced attack reaches your credentials, keys, and system files.

muthr keeps agent execution inside containers backed by Apple container tooling. Each sandbox mounts only the project directory. Your home folder stays out of scope.

Containers give you:

• filesystem boundaries: project files only, no $HOME
• process isolation: agent tools run in a separate user namespace
• deterministic teardown: muthr shutdown stops every managed component cleanly

Mount model

muthr maps your working directory to the container's /workspace path.

~/src/homepage → muthr-homepage container → /workspace
~/src/muthr    → muthr-muthr container    → /workspace

Only project files appear inside the container. Nothing from outside workspace_root mounts by default. If you need files from another location, mount them explicitly.

Runtime environment contract

muthr injects six environment variables into every sandbox session. Agents read these to find the services they need:

Variable	Points to
MUTHR_INFERENCE_URL	Engine inference API
MUTHR_OPENAI_URL	OpenAI-compatible endpoint
MUTHR_MCP_BRIDGE_URL	MCP bridge service
MUTHR_SEARXNG_URL	Search engine
MUTHR_MODEL_NAME	Current model identifier
MUTHR_ENGINE_RUNTIME	Active runtime name

The variables are explicit, not ambient. Agents cannot reach services they are not told about.

Profile provisioning

Profiles configure sandbox environments before you enter them. The flow:

1. muthr checks whether a container exists for the current project
2. It copies the profile provision script and shared library into the container
3. It injects the runtime env contract
4. It runs the provision script as the container user muthr

Provision state gets a content hash (MUTHR_SPECS_REV). If the hash has not changed, muthr skips reinstallation.

Audit logs

Every sandbox start and sandbox shell session can record an audit trail with --audit-log PATH. Each entry is NDJSON and includes:

• session start and exit timestamps
• command argv (for non-TTY sessions)
• TTY mode flag
• runtime env summary

Audit logs stay local. They are useful for incident review and compliance tracking.

---

See also: Sandbox Architecture · Security · Profiles