Skip to content

Deployment

MindRoom can be deployed in various ways depending on your needs.

Deployment Options

Method Best For
Hosted Matrix + local MindRoom Simplest setup: run only uvx mindroom run locally
Sandbox Proxy Isolation Run MindRoom locally while execution tools run in isolated workers
Approved Egress Require static allowlists or human approval before Kubernetes workers reach external hostnames
Full Stack (Docker Compose) All-in-one: bundled dashboard + Matrix (Tuwunel) + MindRoom client
Docker (single container) Single MindRoom runtime or when you already have Matrix
Kubernetes Multi-tenant SaaS, production
Trusted upstream browser auth Hosted private agents behind an authenticated access layer
Direct Development, simple setups

Bridges

Connect external messaging platforms to Matrix:

Google Services (Gmail/Calendar/Drive/Sheets)

Use these guides if you want users to connect Google accounts in the MindRoom frontend:

For private personal-agent tools, use the generic OAuth Framework and the Google Drive section in the individual setup guide. For hosted multi-user private agents, also configure Trusted Upstream Browser Auth so agent-issued OAuth links authenticate as the requester that triggered them.

Quick Start

Hosted Matrix + local MindRoom (simplest)

# Creates ~/.mindroom/config.yaml and ~/.mindroom/.env by default
uvx mindroom config init
$EDITOR ~/.mindroom/.env
uvx mindroom connect --pair-code ABCD-EFGH
uvx mindroom run

Generate the pair code in https://chat.mindroom.chat under: Settings -> Local MindRoom.

See Hosted Matrix deployment for the full walkthrough. If you want worker-routed execution tools like coding, docker, file, python, and shell to run in dedicated Docker workers on the same machine, see Sandbox Proxy Isolation.

git clone https://github.com/mindroom-ai/mindroom-stack
cd mindroom-stack
cp .env.example .env
$EDITOR .env  # add at least one AI provider key

docker compose up -d

The stack exposes MindRoom at http://localhost:8765, the MindRoom client at http://localhost:8080, and Matrix at http://localhost:8008. The stack uses published mindroom, mindroom-cinny, and mindroom-tuwunel images by default. If you access it from another device, set CLIENT_HOMESERVER_URL=http://<host-ip>:8008 in .env before starting it.

Direct (Development)

mindroom run --storage-path ./mindroom_data

The config file path is set via MINDROOM_CONFIG_PATH and otherwise defaults to ./config.yaml, then ~/.mindroom/config.yaml.

If you want local Matrix + Cinny with a host-installed MindRoom runtime (Linux/macOS), use:

mindroom local-stack-setup --synapse-dir /path/to/mindroom-stack/local/matrix
mindroom run --storage-path ./mindroom_data

Docker (single container)

docker run -d \
  --name mindroom \
  -p 8765:8765 \
  -v ./config.yaml:/app/config.yaml:ro \
  -v ./mindroom_data:/app/mindroom_data \
  --env-file .env \
  ghcr.io/mindroom-ai/mindroom:latest

See the Docker deployment guide for the full single-container setup.

Kubernetes

See the Kubernetes deployment guide for Helm chart configuration.

Required Configuration

Full stack:

# .env in the full stack repo
OPENAI_API_KEY=sk-...
# Add other providers as needed

Direct and single-container deployments:

  1. Matrix homeserver - Set MATRIX_HOMESERVER (must allow open registration for agent accounts)
  2. AI provider keys - At least one of OPENAI_API_KEY, OPENROUTER_API_KEY, etc.
  3. Persistent storage - Mount mindroom_data/ to persist agent state (including sessions/, learning/, and memory data)

See the Docker guide for the complete environment variable reference.

Hosted mindroom.chat deployments additionally use values from mindroom connect (MINDROOM_LOCAL_CLIENT_ID, MINDROOM_LOCAL_CLIENT_SECRET, and MINDROOM_NAMESPACE) to bootstrap agent registrations and avoid collisions on shared homeservers.