Skip to content

Deployment

This page helps you choose how to run MindRoom and lists what every deployment needs. Each option links to the page with its setup steps.

Deployment Options

Method Best For
Your computer + MindRoom Chat (hosted Matrix) Recommended and simplest: run only uvx mindroom run locally
Full Stack (Docker Compose) All-in-one: bundled dashboard + Matrix (Tuwunel) + MindRoom client
Agent-managed NixOS container (advanced) Give a MindRoom agent full freedom over its own persistent NixOS machine while the host controls what it sees
Docker (single container) Single MindRoom runtime when you already have Matrix
Direct install Development and simple setups with your own Matrix homeserver
Kubernetes Production clusters: a runtime with optional Tuwunel, client, and MatrixRTC charts, or the multi-tenant SaaS platform
Sandbox Proxy Isolation Run MindRoom while execution tools run in isolated workers
Approved Egress Require static allowlists or human approval before Kubernetes workers reach external hostnames
Trusted upstream browser auth Hosted multi-user private agents behind an authenticated access layer

Required Configuration

The full stack needs only a model provider key in its .env; see Full Stack Docker Compose.

Direct and single-container deployments need:

  1. Matrix homeserver - Set MATRIX_HOMESERVER and give MindRoom a way to create agent accounts (see Matrix account provisioning).
  2. Model credentials - Configure credentials for the selected provider, using an API key or a supported CLI login (see Model Configuration); containers must mount or provide the matching auth state.
  3. Persistent storage - Mount the storage directory (mindroom_data/ by default) so agent state survives restarts (see Data Storage).

Hosted mindroom.chat installs also need the credentials that pairing saves; see Hosted Matrix. Every environment variable is listed in Configuration — Environment Variables.