> For the complete documentation index, see [llms.txt](https://docs.mutx.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mutx.dev/readme.md).

# README

> Source-available control plane for running AI agents in production.

![MUTX dashboard demo](https://2092776695-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlrUGCvqeS10g6J0hLJNu%2Fuploads%2Fgit-blob-16667273a8923d154befb9bd8c835d5dad652417%2Fdemo.gif?alt=media)

Prototype an agent in an afternoon. Run one in production for a year — that's the hard part. Identity, deployments, sessions, health, access control, operator contracts. MUTX makes those explicit in running code, not whitepapers.

## What's in the Box

| Component              | What it does                                                                                                                      |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Control Plane API**  | FastAPI backend — `/v1/*` routes for auth, agents, deployments, sessions, runs, webhooks, budgets, swarms, RAG, and pico progress |
| **Operator Dashboard** | Authenticated dashboard at `app.mutx.dev/dashboard`                                                                               |
| **Landing Site**       | `mutx.dev` — narrative, quickstart, downloads                                                                                     |
| **macOS App**          | Signed & notarized desktop app via `mutx.dev/download/macos`                                                                      |
| **CLI + TUI**          | `mutx` CLI and `mutx tui` — terminal-first workflows                                                                              |
| **Python SDK**         | `pip install mutx` — full control plane access                                                                                    |
| **Document Workflows** | `predict-rlm`-backed document analysis, comparison, extraction, and redaction across API, dashboard, CLI, and worker              |
| **Infrastructure**     | Docker Compose (local), Terraform + Ansible (cloud), Helm (k8s)                                                                   |

## Quick Start

```bash
brew tap mutx-dev/homebrew-tap && brew install mutx
mutx setup hosted
```

Hosted is the default. For the local Docker stack:

```bash
mutx setup local    # Docker-backed
mutx doctor         # Verify everything's wired
```

## Development

```bash
make dev-up                                  # full stack (frontend + backend + Postgres + Redis)
uvicorn src.api.main:app --reload --port 8000  # backend only
npm run dev                                    # frontend only
```

| URL                        | What               |
| -------------------------- | ------------------ |
| `localhost:3000`           | Landing site       |
| `localhost:3000/dashboard` | Operator dashboard |
| `localhost:8000`           | API                |
| `localhost:8000/docs`      | Swagger UI         |

### Validation

```bash
./scripts/test.sh                        # full suite
npm run build                            # frontend build
npm run typecheck                        # TS gate
npm run test:app                         # frontend unit tests
ruff check src/api cli sdk  # Python lint
.venv/bin/python -m pytest               # API tests (from repo venv)
npx playwright test                       # e2e
```

Playwright starts a fresh local standalone server by default so worktree runs fail closed instead of silently reusing a stale build. Set `PLAYWRIGHT_REUSE_EXISTING_SERVER=1` only when you intentionally want to target an already running local standalone server.

## Architecture

```
mutx.dev ──────────── Next.js landing + releases + download
app.mutx.dev ──────── Dashboard + control demo + browser proxies
src/api/ ──────────── FastAPI control plane (/v1/*)
cli/ ──────────────── Click CLI + Textual TUI
sdk/mutx/ ─────────── Python SDK
infrastructure/ ───── Docker, Terraform, Ansible, Helm, monitoring
agents/ ───────────── Autonomous specialist agent definitions
```

Governance via [Faramesh](https://faramesh.dev) — policy enforcement, session budgets, phase workflows, credential brokering, rate limiting. Auth is RBAC + OIDC (Okta, Auth0, Azure AD, Keycloak).

## Go Deeper

* [Manifesto](broken://pages/f8t5UsekyJ55q7qAJoXV) — why control planes, not demos
* [Technical Whitepaper](broken://pages/66hNWgtXEIsEJvudX6Ax) — architecture deep-dive
* [Roadmap](broken://pages/xKLSAXp0lAyggwTgdL1i) — what's next
* [API Reference](/reference.md) — `/v1/*` contract
* [CLI Guide](/overview/cli.md) — terminal workflows
* [Document Workflows](/overview/document-workflows.md) — `predict-rlm` requirements, API, CLI, dashboard, and worker
* [Python SDK](/sdk.md) — programmatic access
* [v1.4 Release Notes](/v1.4.md) — latest release
* [v1.3 Release Notes](broken://pages/iYjMONI5UalteWNBXrLd) — previous release
* [Contributing](https://github.com/mutx-dev/mutx-dev/blob/main/CONTRIBUTING.md) — repo conventions
* [Infrastructure](broken://pages/R8oUkIKbqRb7KxGdBlzX) — deploy guide

## Built On

* [agent-run](https://github.com/builderz-labs/agent-run) — observability standard
* [AARM](https://github.com/aarm-dev/docs) — Autonomous Action Runtime Management
* [Faramesh](https://github.com/faramesh/faramesh-core) — governance engine
* [Mission Control](https://github.com/builderz-labs/mission-control) — fleet management
* [predict-rlm](https://github.com/Trampoline-AI/predict-rlm) — document workflow engine and upstream example surface for analysis, comparison, invoice extraction, and redaction

Full attribution in [CREDITS.md](https://github.com/mutx-dev/mutx-dev/blob/main/CREDITS.md).

## License

Source-available under [BUSL-1.1](https://github.com/mutx-dev/mutx-dev/blob/main/LICENSE/README.md). Each release converts to Apache-2.0 after 36 months. Python SDK is [Apache-2.0](https://github.com/mutx-dev/mutx-dev/blob/main/sdk/LICENSE/README.md). See [LICENSE-FAQ](https://github.com/mutx-dev/mutx-dev/blob/main/LICENSE-FAQ.md).

Commercial use (hosted, managed, OEM) requires a license — <hello@mutx.dev>.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.mutx.dev/readme.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.