muthr

Zero-trust orchestrator for local AI on Apple Silicon.

Run MLX or GGUF inference on the host, isolate agent runtimes inside per-project containers, and expose stable MCP + search endpoints. Host OS, SSH keys, and home directory stay on the host.

Quick Start · Features · Architecture · Commands · Configuration · Full Docs

Quick Start

Three commands to a safe agent sandbox:

brew install tappunk/muthr/muthr    # or: cargo install muthr
muthr init                          # populate config from muthr-specs
muthr run                           # boot engine + services

Then enter a project sandbox:

cd ~/src/myproject
muthr sandbox shell --profile opencode

That's it. Inference runs on the host. Your agent runs isolated inside a container with only the project workspace mounted. Host secrets stay on the host.

Features

• Host inference management: runs mlxcel-server, llama-server, or vllm-mlx with an OpenAI-compatible API surface
• Per-project sandbox containers: deterministic lifecycle, profile-aware provisioning, interactive shell with TTY resize forwarding
• Persistent MCP services: MCP bridge + SearXNG search in a long-lived services container
• Zero-trust isolation: agents get workspace access only. No host OS, SSH keys, or home directory
• Session audit trail: optional NDJSON logs (session_start, exec_invocation, session_exit) for forensics
• Golden images: pre-bake profile images for restricted or air-gapped environments
• Doctor diagnostics: proactive backend checks including arm64 buildkit/Rosetta probing
• Full lifecycle: muthr run boots engine + services, muthr shutdown tears down everything
• Machine-readable output: --output json|ndjson on status/list commands
• Shell completions: bash, zsh, fish, powershell

Architecture

┌──────────────────── macOS Host ──────────────────────┐
│                                                      │
│  ┌──────────────┐          ┌──────────────────┐      │
│  │ mlxcel-server│          │ muthr-services   │      │
│  │  or          │          │  MCP Bridge      │      │
│  │ llama-server │          │  SearXNG         │      │
│  │  or          │          │                  │      │
│  │ vllm-mlx     │          │                  │      │
│  └──────┬───────┘          └──────────────────┘      │
│         │                                            │
│  ┌──────┴───────┐                                    │
│  │ Sandboxes    │                                    │
│  │ (container)  │                                    │
│  └──────────────┘                                    │
│                                                      │
│  Agent access: workspace mount + OpenAI URL          │
│  Host secrets/SSH/home remain outside sandbox        │
│                                                      │
└──────────────────────────────────────────────────────┘

muthr orchestrates three layers:

1. Host inference runtime: mlxcel-server, llama-server, or vllm-mlx managed by muthr engine
2. Persistent services plane: muthr-services + muthr-searxng managed by muthr services
3. Per-project sandbox: one container per project directory, managed by muthr sandbox

The default muthr run path boots engine + services, then you enter project sandboxes as needed.

Usage

Engine

muthr engine start --profile mlx-community/Qwen3.5-9B-MLX-4bit
muthr engine start --runtime llama --profile ~/opt/models/my-model.gguf
muthr engine start --runtime mlxcel --engine-server-port 8081 --foreground
muthr engine start --runtime vllm-mlx --profile mlx-community/Qwen3.5-9B-MLX-4bit
muthr engine status --output json
muthr engine presets --runtime llama --output json
muthr engine stop --all

Sandbox

cd ~/src/myproject
muthr sandbox start --profile opencode --audit-log ~/audit.ndjson
muthr sandbox shell                          # interactive shell
muthr sandbox shell -c "cargo test"          # non-interactive command
muthr sandbox shell -e API_KEY=abc --no-tty  # explicit env + automation
muthr sandbox ls --quiet                     # one name per line for scripting
muthr sandbox stop --all
muthr sandbox delete --dry-run               # preview before deleting
muthr sandbox stop --name muthr-myproject

Golden images

muthr image build --profile hermes-agent

Services

muthr services start --dry-run
muthr services status --output json
muthr services restart --dry-run
muthr services stop --dry-run
muthr services delete --yes

Full lifecycle

muthr run --verbose
muthr shutdown --yes

Commands

Configuration

Config lives in ~/.config/muthr/muthr.toml:

server_port = 8080
workspace_root = "~/src"
model_dir = "~/opt/models"
default_provision_profile = "opencode"
default_engine_runtime = "mlxcel"
default_engine_profile = "mlx-community/Qwen3.5-9B-MLX-4bit"
default_engine_bind_host = "0.0.0.0"
container_host_gateway = "host.docker.internal"

Key environment overrides: MUTHR_SERVER_PORT, MUTHR_WORKSPACE_ROOT, MUTHR_MODEL_DIR, MUTHR_PROVISION_PROFILE, MUTHR_ENGINE_RUNTIME, MUTHR_ENGINE_PROFILE, MUTHR_ENGINE_BIND_HOST, MUTHR_CONTAINER_HOST_GATEWAY.

Profiles (base, opencode, hermes-agent) define container provisioning. Profile assets are managed via muthr-specs.

Security

muthr's design premise: running AI agents on your host is high-risk. Agents execute package installers, shell commands, and network clients with broad filesystem access.

muthr mitigates this by:

• Running agents inside sandbox containers, never on the host shell
• Mounting only the project workspace (/workspace) into containers
• Exposing inference endpoints via explicit env vars, not ambient host access
• Using Apple container for native virtualization-backed isolation

See Security for the full threat model.

Why this exists

Running AI agents directly on your host is high-risk. A single compromised dependency, malicious prompt chain, or unsafe tool invocation can leak credentials or compromise the system.

muthr isolates agent execution into containers. Host-only assets stay on the host. Everything stays observable and auditable.

Contributing

Issues and PRs welcome. See the full docs for development setup and architecture details.

Acknowledgements

• llama.cpp
• mlxcel
• vllm-mlx
• Apple container

Full documentation: https://tappunk.com/muthr/