Docker Deployment

Deploy MindRoom using Docker for simple, containerized deployments.

Quick Start

MindRoom ships as a single runtime container that serves:

• the bot orchestrator
• the dashboard UI at http://localhost:8765
• the dashboard API at http://localhost:8765/api
• the OpenAI-compatible API at http://localhost:8765/v1

Run it with:

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

Docker Compose

Create a docker-compose.yml:

services:
  mindroom:
    image: ghcr.io/mindroom-ai/mindroom:latest
    container_name: mindroom
    restart: unless-stopped
    ports:
      - "8765:8765"
    volumes:
      - ./config.yaml:/app/config.yaml:ro
      - ./mindroom_data:/app/mindroom_data
    env_file:
      - .env
    environment:
      - MINDROOM_STORAGE_PATH=/app/mindroom_data
      - LOG_LEVEL=${LOG_LEVEL:-INFO}
      - MATRIX_HOMESERVER=${MATRIX_HOMESERVER}
      # Optional: for self-signed certificates
      # - MATRIX_SSL_VERIFY=false
      # Optional: override server name for federation
      # - MATRIX_SERVER_NAME=example.com

Run with:

docker compose up -d

Environment Variables

Key environment variables (set in .env or pass directly):

To change the API server port or bind address, pass --api-port or --api-host to the mindroom run command. For example, add command: ["mindroom", "run", "--api-port", "9000"] to the Docker Compose service.

Streaming responses are configured in config.yaml via defaults.enable_streaming (default: true).

If MINDROOM_API_KEY is set, the browser dashboard will prompt for the key via a same-origin login page before loading the UI.

Building from Source

Build from the repository root:

docker build -t mindroom:dev -f local/instances/deploy/Dockerfile.mindroom .

The Dockerfile uses a multi-stage build with uv for dependency management and runs as a non-root user (UID 1000).

A Dockerfile.mindroom-minimal variant is also available, which builds a smaller image without pre-installed tool extras -- useful for sandbox runners.

With Local Matrix

For development, run MindRoom alongside a local Matrix server:

# Start Matrix (Synapse + Postgres + Redis)
cd local/matrix && docker compose up -d

# Verify Matrix is running
curl -s http://localhost:8008/_matrix/client/versions

# Start MindRoom using the docker-compose.yml you created above
docker compose up -d

The local Matrix stack includes:

• Synapse: Matrix homeserver on port 8008
• PostgreSQL: Database backend
• Redis: Caching layer

If you're running the backend on the host (not in Docker), you can use mindroom local-stack-setup to start Synapse + MindRoom Cinny and persist local Matrix env vars automatically:

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

Health Checks

The container exposes a health endpoint on port 8765:

curl http://localhost:8765/api/health

Data Persistence

MindRoom stores data in the mindroom_data directory:

• sessions/ - Per-agent conversation history (SQLite)
• learning/ - Per-agent Agno Learning state (SQLite, persistent across restarts)
• chroma/ - ChromaDB vector store for agent/team memories
• knowledge_db/ - Knowledge base vector stores
• culture/ - Shared culture state
• tracking/ - Response tracking to avoid duplicates
• credentials/ - Synchronized secrets from .env
• logs/ - Application logs
• matrix_state.yaml - Matrix connection state
• encryption_keys/ - Matrix E2EE keys (if enabled)

Sandbox Proxy Isolation

When configured, coding, docker, file, python, and shell tool calls can be proxied to a separate sandbox-runner sidecar container. The sidecar runs the same image but without access to secrets, credentials, or the primary data volume. This provides real process-level isolation for code-execution tools. In a simple local static-runner install with no proxy URL, execution tools continue to run in the MindRoom process. When routing is explicitly requested or a dedicated worker backend is configured, misconfigured worker routing fails closed instead of silently falling back to the primary runtime.

See Sandbox Proxy Isolation for full documentation including Docker Compose examples, Kubernetes shared-sidecar and dedicated-worker modes, host-machine-with-container mode, credential leases, and environment variable reference.