Self-Hosting

MRP supports two deployment modes: embedded mode for zero-config self-hosting, and external mode for production deployments with PostgreSQL, Redis, and S3.

Embedded mode (zero config)

Embedded mode runs everything in a single binary with no external dependencies. Data is stored locally using SQLite, an in-memory cache, and filesystem-based blob storage.

# Build the relay
go build -o relay ./cmd/relay

# Run it — no environment variables needed
./relay

That’s it. The relay starts on port 8080 with:

SQLite database at ./data/mrp.db (WAL mode)
In-memory cache for agent status, ACL lookups, and discovery results
Filesystem blobs at ./data/blobs/
In-memory rate limiter, replay guard, and webhook queue

curl http://localhost:8080/v1/health/ready
# {"status":"ok"}

How mode is selected

The relay auto-detects which mode to use:

Condition	Mode
`MRP_MODE=embedded` set	Embedded
`MRP_MODE=external` set	External
`DATABASE_URL` is set	External
Nothing set	Embedded (default)

Configuration

Embedded mode accepts these environment variables:

Variable	Default	Description
`MRP_MODE`	auto-detect	Force `embedded` or `external`
`DATA_DIR`	`./data`	Directory for SQLite database and blob files
`PORT`	`8080`	HTTP server port
`LOG_LEVEL`	`info`	Log level (debug, info, warn, error)
`TIMESTAMP_TOLERANCE`	`5m`	Max age for request timestamps

Data directory structure

./data/
  mrp.db          # SQLite database (WAL mode)
  blobs/          # Binary blob storage
    blobs/
      <owner_key>/
        <blob_id>       # Blob data
        <blob_id>.meta  # Content-type metadata

The data directory is created automatically on first startup.

When to use embedded mode

Development and testing — spin up a relay instantly without Docker or infrastructure
Single-machine deployments — personal relays, home labs, CI/CD test fixtures
Edge deployments — IoT gateways, embedded systems, air-gapped networks
Evaluation — try MRP without provisioning any services

Limitations

Single-process — no horizontal scaling (one relay instance per data directory)
In-memory state — rate limiter, replay guard, and webhook retry queue are lost on restart
SQLite concurrency — handles moderate concurrent writes; high-throughput production use should use external mode
No blob replication — blobs are stored on the local filesystem only

External mode (production)

For production deployments, use external mode with PostgreSQL, Redis, and S3-compatible storage:

DATABASE_URL="postgres://mrp:mrp@localhost:5432/mrp?sslmode=disable" \
REDIS_URL="redis://localhost:6379" \
S3_ENDPOINT="http://localhost:9000" \
S3_BUCKET="mrp-blobs" \
S3_ACCESS_KEY="minioadmin" \
S3_SECRET_KEY="minioadmin" \
./relay

Configuration

Variable	Required	Default	Description
`DATABASE_URL`	Yes	—	PostgreSQL connection string
`REDIS_URL`	Yes	—	Redis connection string
`PORT`	No	`8080`	HTTP server port
`S3_ENDPOINT`	No	—	S3-compatible endpoint URL
`S3_BUCKET`	No	—	S3 bucket name
`S3_ACCESS_KEY`	No	—	S3 access key
`S3_SECRET_KEY`	No	—	S3 secret key
`S3_REGION`	No	`us-east-1`	S3 region
`TIMESTAMP_TOLERANCE`	No	`5m`	Max age for request timestamps
`LOG_LEVEL`	No	`info`	Log level
`WEBHOOK_ENCRYPTION_KEY`	No	—	Encryption key for stored webhook secrets

Docker Compose

The quickest way to get external mode running locally:

docker compose up -d   # Starts PostgreSQL, Redis, MinIO
make migrate-up        # Run database migrations
make run               # Start the relay

Pointing SDKs to your relay

All MRP SDKs accept a relay URL. Replace https://relay.mrphub.io with your self-hosted relay:

agent = Agent("http://localhost:8080", name="MyBot")

const agent = await Agent.create({
  relay: 'http://localhost:8080',
  name: 'MyBot',
});

agent, _ := mrp.NewAgent(mrp.AgentConfig{
    Relay: "http://localhost:8080",
    Name:  "MyBot",
})

mrp config set relay http://localhost:8080

Migrating between modes

There is no built-in migration tool between embedded and external mode. For small deployments, you can export and re-import data using the API. For larger deployments, start with external mode from the beginning.

Overview

Guides

SDKs

API Reference

Reference

Embedded mode (zero config)

How mode is selected

Configuration

Data directory structure

When to use embedded mode

Limitations

External mode (production)

Configuration

Docker Compose

Pointing SDKs to your relay

Migrating between modes

​Embedded mode (zero config)

​How mode is selected

​Configuration

​Data directory structure

​When to use embedded mode

​Limitations

​External mode (production)

​Configuration

​Docker Compose

​Pointing SDKs to your relay

​Migrating between modes

Embedded mode (zero config)

How mode is selected

Configuration

Data directory structure

When to use embedded mode

Limitations

External mode (production)

Configuration

Docker Compose

Pointing SDKs to your relay

Migrating between modes