# MUXI Registry - Docker Hub for AI Formations

> Discover, share, and deploy complete AI agent systems with one command.

## What is MUXI Registry?

MUXI Registry is the central hub for discovering and distributing AI formations. Think Docker Hub, but for AI agents. One command (`muxi pull @user/formation`) gets you a production-ready multi-agent system.

**Core Value:** Share complete, working AI systems instantly. No configuration headaches. No dependency hunting. Just pull and deploy.

## How It Works

```bash
# Pull a formation
muxi pull @muxi/customer-support

# Deploy it
muxi deploy
```

That's it. The formation includes everything: agents, tools, knowledge, procedures, and configurations.

## Key Features

### For Users

- **One-command deployment**: `muxi pull @user/formation` downloads everything you need
- **Version pinning**: Pull specific versions with `@user/formation:1.2.0`
- **Lazy discovery**: Any `muxi-*` GitHub repo is automatically discoverable
- **GitHub-backed**: Formations stored as GitHub releases with full version history

### For Publishers

- **Simple publishing**: `muxi push` uploads your formation to the registry
- **Organization support**: Publish under your org (`@acme/sales-bot`)
- **Automatic versioning**: Semantic versioning with GitHub releases
- **Stats tracking**: Download counts, stars, and usage metrics

## What's in a Formation?

A formation is a complete AI system defined in the [Agent Formation Standard](https://agentformation.org):

- **Agents**: AI agent definitions with models, prompts, and behaviors
- **MCPs**: Tool connections (GitHub, Slack, databases, APIs)
- **Knowledge**: Domain files, documents, and RAG configurations
- **SOPs**: Standard Operating Procedures agents reason over
- **Triggers**: Schedules and webhooks for automation
- **Settings**: Environment variables and configurations

All packaged in a `formation.yaml` file, version-controlled and portable.

## URL Structure

```
https://registry.muxi.org/@username              # User profile
https://registry.muxi.org/@username/formation    # Formation page
https://registry.muxi.org/browse                 # Browse all formations
https://registry.muxi.org/search?q=query         # Search formations
```

## API Endpoints

```bash
# Get formation info
GET /api/formations/@user/name

# Get specific version
GET /api/formations/@user/name:1.2.0

# Pull formation (tracks download)
GET /api/formations/@user/name?pull=true

# Publish formation (authenticated)
POST /api/formations/publish
Authorization: Bearer mxr_xxx
Content-Type: multipart/form-data
```

## Authentication

The registry uses GitHub OAuth for authentication:

1. Sign in with your GitHub account
2. Get an API token (`mxr_xxx`) for CLI operations
3. Publish formations under your username or organizations

## Quick Start

### Pull a Formation

```bash
# Install MUXI CLI
curl -fsSL https://muxi.org/install | sudo bash

# Pull a formation
muxi pull @muxi/bookkeeping

# Set your API keys
muxi secrets set OPENAI_API_KEY sk-xxx

# Deploy
muxi deploy
```

### Publish a Formation

```bash
# Login to registry
muxi login

# Create your formation
muxi init my-formation

# Publish
muxi push
```

## Popular Formations

Browse formations at [registry.muxi.org/browse](https://registry.muxi.org/browse):

- **@muxi/customer-support** - Multi-agent customer service team
- **@muxi/bookkeeping** - Automated bookkeeping and invoicing
- **@muxi/code-review** - AI-powered code review assistant

## GitHub Integration

The registry is GitHub-backed:

- **Storage**: Formations stored in `muxi-*` repos
- **Versions**: Git tags become formation versions
- **Releases**: ZIP bundles attached to GitHub releases
- **Discovery**: Any public `muxi-*` repo is auto-discoverable

### Repository Naming

| Formation | GitHub Repo | Registry URL |
|-----------|-------------|--------------|
| customer-support | `muxi-customer-support` | `@user/customer-support` |
| sales-bot | `muxi-sales-bot` | `@user/sales-bot` |

## Related Resources

- **MUXI Stack**: https://muxi.org - The infrastructure that runs formations
- **Agent Formation Standard**: https://agentformation.org - The open spec
- **MUXI Documentation**: https://muxi.org/docs
- **GitHub**: https://github.com/muxi-ai

## Community

- **GitHub Discussions**: https://muxi.org/community
- **Twitter**: @muxi_ai
- **Email**: hi@muxi.org

## Licensing

- **MUXI Server and Runtime**: Elastic License 2.0 (ELv2)
- **Everything else**: Apache 2.0

---

**Updated**: January 2026
**Registry URL**: https://registry.muxi.org