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) without changing directories
docker compose -f local/matrix/docker-compose.yml up -d

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

# Start MindRoom using the docker-compose.yml you created above.
# Its MATRIX_HOMESERVER must resolve from inside the MindRoom container.
docker compose up -d

The two Compose projects do not share a network automatically. Either attach both services to one named external network and use the Synapse service name, such as http://mindroom-synapse:8008, or configure an explicit host-gateway address. Do not use http://localhost:8008 inside the MindRoom container; there, localhost means the MindRoom container itself.

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 Chat 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 by default:

• agents/*/sessions/ and teams/*/sessions/ - Conversation history (SQLite), optionally rooted at MINDROOM_SESSION_STORAGE_PATH
• 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/ - Durable response, callback-obligation, and lifecycle-hook state used to prevent duplicate work across restarts
• credentials/ - Synchronized secrets from .env
• logs/ - Application logs
• matrix_state.yaml - Matrix connection state
• encryption_keys/ - Matrix E2EE keys (if enabled)

Keep tracking/ on persistent storage and include it in backups. When MINDROOM_SESSION_STORAGE_PATH is set in a container, mount that path on persistent storage and include it in backups too. Dispatch-obligation databases retain one compact terminal row per settled callback except successful invites, whose synthetic obligations are deleted so later re-invites can run. The retained terminal rows have no automatic retention window because deleting them weakens replay deduplication. Pending rows temporarily retain the full event replay payload and should represent only actively deferred or retry-owned work, not completed ignore paths. Checkpoint invalidation can force a no-since limited sync that backfills older events, and opaque Matrix tokens provide no safe ordering frontier for pruning those exact keys. Size and monitor the volume for lifetime callback growth, and use the inspection and corruption-remediation guidance in Bot Runtime Architecture.

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.