MindRoom

https://docs.mindroom.chat
Admin
MindRoom is an AI agent orchestration system that deploys autonomous multi-agent teams in Matrix...
Tokens:337,513
Snippets:2,916
Trust Score:4.8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Start Local Stack Setup

Source: https://docs.mindroom.chat/cli

Initializes the local Synapse and Cinny stack at the specified directory.

```bash
mindroom local-stack-setup --synapse-dir /path/to/mindroom-stack/local/matrix
```

--------------------------------

### Start local Matrix and MindRoom services

Source: https://docs.mindroom.chat/deployment/docker

Start the Matrix stack and verify the service, then start the MindRoom container. Ensure MATRIX_HOMESERVER is configured to resolve correctly from within the container.

```bash
# 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
```

--------------------------------

### Start llama.cpp server

Source: https://docs.mindroom.chat/cli

Commands to start the llama.cpp server with specific model references for the llama.cpp provider preset.

```bash
llama-server -hf unsloth/gemma-4-26B-A4B-it-GGUF:UD-Q4_K_M --host 127.0.0.1 --port 8080
llama-server -hf unsloth/Qwen3.8-27B-GGUF:UD-Q4_K_XL --host 127.0.0.1 --port 8080
```

--------------------------------

### Install MindRoom with pip

Source: https://docs.mindroom.chat/getting-started

Install MindRoom using pip as an alternative to uv.

```bash
pip install mindroom

```

--------------------------------

### GET /api/skills

Source: https://docs.mindroom.chat/dashboard

Lists all installed skills.

```APIDOC
## GET /api/skills

### Description
Lists all installed skills.

### Method
GET

### Endpoint
/api/skills
```

--------------------------------

### Install MindRoom from source

Source: https://docs.mindroom.chat/getting-started

Clone the MindRoom repository and set up the environment with uv sync, then activate the virtual environment.

```bash
git clone https://github.com/mindroom-ai/mindroom
cd mindroom
uv sync
source .venv/bin/activate

```

--------------------------------

### Configure environment variables

Source: https://docs.mindroom.chat/getting-started

Create the .env file from the example and open it in an editor to add AI provider keys.

```bash
cp .env.example .env
$EDITOR .env  # add at least one AI provider key
```

--------------------------------

### Invoke make_request calls

Source: https://docs.mindroom.chat/tools/automation-and-platforms

Examples of using the make_request function to perform GET and POST operations.

```python
make_request("health")
make_request("users/42", method="GET")
make_request("reports", method="POST", json_data={"range": "7d"})
```

--------------------------------

### local-stack-setup CLI Usage

Source: https://docs.mindroom.chat/cli

Displays the available options and default values for the local-stack-setup command.

```text
 Usage: root local-stack-setup [OPTIONS]

 Start local Synapse + MindRoom Chat using Docker only.

╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --synapse-dir                                 PATH                 Directory           │
│                                                                    containing Synapse  │
│                                                                    docker-compose.yml  │
│                                                                    (from               │
│                                                                    mindroom-stack      │
│                                                                    settings).          │
│                                                                    [default:           │
│                                                                    local/matrix]       │
│ --homeserver-url                              TEXT                 Homeserver URL that │
│                                                                    MindRoom Chat and   │
│                                                                    MindRoom should     │
│                                                                    use.                │
│                                                                    [default:           │
│                                                                    http://localhost:8… │
│ --server-name                                 TEXT                 Matrix server name  │
│                                                                    (default: inferred  │
│                                                                    from                │
│                                                                    --homeserver-url    │
│                                                                    hostname).          │
│ --cinny-port                                  INTEGER RANGE        Local host port for │
│                                               [1<=x<=65535]        the MindRoom Chat   │
│                                                                    container.          │
│                                                                    [default: 8080]     │
│ --cinny-image                                 TEXT                 Docker image for    │
│                                                                    MindRoom Chat.      │
│                                                                    [default:           │
│                                                                    ghcr.io/mindroom-a… │
│ --cinny-container-n…                          TEXT                 Container name for  │
│                                                                    MindRoom Chat       │
│                                                                    (legacy default     │
│                                                                    retained for        │
│                                                                    compatibility).     │
│                                                                    [default:           │
│                                                                    mindroom-cinny-loc… │
│ --skip-synapse                                                     Skip starting       │
│                                                                    Synapse (assume it  │
│                                                                    is already          │
│                                                                    running).           │
│ --persist-env             --no-persist-env                         Persist Matrix      │
│                                                                    local dev settings  │
│                                                                    to .env next to     │
│                                                                    config.yaml.        │
│                                                                    [default:           │
│                                                                    persist-env]        │
│ --help                -h                                           Show this message   │
│                                                                    and exit.           │
╰────────────────────────────────────────────────────────────────────────────────────────╯
```

--------------------------------

### Initialize local configuration

Source: https://docs.mindroom.chat/getting-started

Initializes the MindRoom configuration files in ~/.mindroom/.

```bash
uvx mindroom config init
```

--------------------------------

### Agent Instructions for Interactive Questions

Source: https://docs.mindroom.chat/interactive

Example configuration for guiding an agent to utilize interactive code blocks within its instructions.

```yaml
agents:
  assistant:
    display_name: Assistant
    role: A helpful assistant
    instructions:
      - >
        When the user needs to choose between options, present them using
        an interactive code block with JSON containing question and options
        (each with emoji, label, and value fields).
```

--------------------------------

### Start Local Stack without Persisting Environment

Source: https://docs.mindroom.chat/cli

Runs the local stack setup without writing the configuration to a .env file.

```bash
mindroom local-stack-setup --no-persist-env
```

--------------------------------

### Invoke Confluence tool methods

Source: https://docs.mindroom.chat/tools/project-management

Examples of calling Confluence tool methods to retrieve space details, get page content, and create a new page.

```text
get_all_space_detail()
get_page_content("Engineering", "Runbook")
create_page("Engineering", "Release Notes", "<p>Initial draft</p>")
```

--------------------------------

### Bootstrap local Synapse from source

Source: https://docs.mindroom.chat/getting-started

Run the local-stack-setup command using uv run when running MindRoom from source.

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

```

--------------------------------

### Invoke Discord tool functions

Source: https://docs.mindroom.chat/tools/messaging-and-social

Examples of calling Discord tool functions such as listing channels, getting info, fetching messages, and sending a message using a channel ID.

```python
list_channels("123456789012345678")
get_channel_info("123456789012345678")
get_channel_messages("123456789012345678", limit=25)
send_message("123456789012345678", "Hello from MindRoom.")
```

--------------------------------

### Full Team Configuration Example

Source: https://docs.mindroom.chat/configuration/teams

A comprehensive example showing all available configuration options for a team, including rooms, invite settings, model selection, and compaction settings.

```yaml
teams:
  super_team:
    # Display name shown in Matrix
    display_name: Super Team

    # Description of the team's purpose (required)
    role: Multi-disciplinary team for complex tasks

    # Agents in this team (must be defined in agents section)
    agents:
      - code
      - research
      - finance

    # Collaboration mode: coordinate or collaborate (default: coordinate)
    mode: collaborate

    # Rooms the team responds in
    rooms:
      - team-room

    # Accept all, none, or matching inviter ID patterns
    accept_invites: true

    # Model for team coordination (default: "default")
    model: sonnet


    # Team-scoped replay controls (optional; inherit from defaults when omitted)
    num_history_runs: 8
    num_history_messages: null
    max_tool_calls_from_history: 6

    # Team-scoped required-compaction overrides (optional)
    # Soft thresholds do not compact by themselves while history still fits.
    compaction:
      enabled: true
      threshold_percent: 0.8
      reserve_tokens: 16384
      timeout_seconds: 600
```

--------------------------------

### !desktop command variants

Source: https://docs.mindroom.chat/chat-commands

Run these commands in a private Matrix room containing only the requester and one Desktop-enabled agent, plus the router when it serves the command. !desktop setup returns a local 'mindroom desktop setup' command and a short-lived pairing code; !desktop rotate starts the same flow while leaving the current target active until confirmation.

```text
!desktop setup
!desktop status
!desktop confirm <code> <verification>
!desktop rotate
!desktop disconnect
!desktop disconnect confirm
```

--------------------------------

### Initialize MindRoom configuration

Source: https://docs.mindroom.chat/cli

Creates a starter config.yaml with specified Matrix server and model provider presets.

```bash
# Hosted Matrix quickstart (creates ~/.mindroom/config.yaml)
mindroom config init

# Self-hosted Matrix with Anthropic
mindroom config init --matrix-server self-hosted --provider anthropic

# Hosted Matrix with a Codex CLI ChatGPT login
mindroom config init --matrix-server mindroom.chat --provider codex

# Hosted Matrix with Ollama
mindroom config init --matrix-server mindroom.chat --provider ollama

# Hosted Matrix with llama.cpp
mindroom config init --matrix-server mindroom.chat --provider llama.cpp

# Hosted Matrix with Vertex AI Claude
mindroom config init --matrix-server mindroom.chat --provider vertexai_claude

# Preview generated YAML without writing files
mindroom config init --matrix-server mindroom.chat --provider ollama --print

# Force overwrite existing config
mindroom config init --force
```

--------------------------------

### Use spotify tool methods for search, top tracks, playlist creation, and playback

Source: https://docs.mindroom.chat/tools/media-and-content

Python-like usage examples for the spotify tool: searching tracks, getting top tracks, creating a playlist, and checking currently playing. These methods require appropriate Spotify scopes beyond the base dashboard flow.

```python
search_tracks("ambient coding music", max_results=5)
get_my_top_tracks(time_range="short_term", limit=10)
create_playlist("MindRoom Picks", description="Tracks from this week's chat")
get_currently_playing()

```

--------------------------------

### Configure deferred tools in agent YAML

Source: https://docs.mindroom.chat/tools/dynamic-tools

Example agent configuration showing eager, deferred, and initial tools. `defer: true` hides the tool schema until loaded; `initial: true` loads at session start and prevents unloading. The `initial` flag requires `defer: true`. Lazy loading is per-agent, so `defaults.tools` and tool presets do not accept these flags.

```yaml
agents:
  assistant:
    display_name: Assistant
    role: Help in chat
    tools:
      - shell
      - coding: {defer: true, initial: true, restrict_to_base_dir: false}
      - searxng: {defer: true, host: https://search.example.test, fixed_max_results: 10}
      - name: serper
        defer: true
        overrides: {num_results: 10}

```

--------------------------------

### Connect with custom provisioning URL

Source: https://docs.mindroom.chat/cli

Pairs the local install using a non-default provisioning URL.

```bash
mindroom connect \
  --pair-code ABCD-EFGH \
  --provisioning-url https://matrix.example.com
```

--------------------------------

### Set up .env environment variables

Source: https://docs.mindroom.chat/getting-started

Environment variables for Matrix homeserver, AI provider API keys, and optional settings for registration token, SSL verification, server name, and dashboard API key.

```bash
# Matrix homeserver must allow managed account provisioning.
MATRIX_HOMESERVER=https://matrix.example.com

# Recommended when the homeserver supports token-gated registration.
# MATRIX_REGISTRATION_TOKEN=your-registration-token

# Optional: For self-signed certificates (development)
# MATRIX_SSL_VERIFY=false

# Optional: For federation setups where server_name differs from homeserver hostname
# MATRIX_SERVER_NAME=example.com

# AI provider API keys
OPENAI_API_KEY=your_openai_key
# OPENROUTER_API_KEY=your_openrouter_key
# ANTHROPIC_API_KEY=your_anthropic_key

# Optional: protect the dashboard API (recommended for non-localhost)
# MINDROOM_API_KEY=your-secret-key

```

--------------------------------

### GET /api/credentials/{service}

Source: https://docs.mindroom.chat/dashboard

Gets credentials for editing.

```APIDOC
## GET /api/credentials/{service}

### Description
Gets credentials for editing.

### Method
GET

### Endpoint
/api/credentials/{service}

### Path Parameters
- **service** (string) - Required - The service name

### Query Parameters
- **agent_name** (string) - Optional - Scope credentials to a specific agent
- **execution_scope** (string) - Optional - Scope credentials to a specific worker scope (e.g., shared, unscoped)

### Response
#### Success Response (200)
- Credentials for editing
```

--------------------------------

### Initialize Local Config with uvx mindroom config init

Source: https://docs.mindroom.chat/deployment/hosted-matrix

Initializes local configuration with hosted defaults, creating ~/.mindroom/config.yaml and ~/.mindroom/.env. Use --provider codex to set provider: codex in the starter config.

```bash
uvx mindroom config init

```

--------------------------------

### GET /api/config/room-models

Source: https://docs.mindroom.chat/dashboard

Gets room model overrides.

```APIDOC
## GET /api/config/room-models

### Description
Gets room model overrides.

### Method
GET

### Endpoint
/api/config/room-models

### Response
#### Success Response (200)
- Room model overrides
```

--------------------------------

### Install plugins via CLI

Source: https://docs.mindroom.chat/plugins

Commands to install plugins from GitHub using bare names or specific references. The process includes validation and locking the installed commit.

```bash
mindroom plugins install ping-hook-plugin
mindroom plugins install mindroom-ai/ping-hook-plugin@v1.2.0
```

--------------------------------

### GET /api/credentials/{service}/status

Source: https://docs.mindroom.chat/dashboard

Gets credential status for a service.

```APIDOC
## GET /api/credentials/{service}/status

### Description
Gets credential status for a service.

### Method
GET

### Endpoint
/api/credentials/{service}/status

### Path Parameters
- **service** (string) - Required - The service name

### Query Parameters
- **agent_name** (string) - Optional - Scope credentials to a specific agent
- **execution_scope** (string) - Optional - Scope credentials to a specific worker scope (e.g., shared, unscoped)

### Response
#### Success Response (200)
- Credential status
```

--------------------------------

### Deploy full Docker Compose stack

Source: https://docs.mindroom.chat/deployment

Clones the mindroom-stack repo, copies .env.example, edits .env to add AI provider keys, and runs quickstart script. Quickstart validates provider config, waits for readiness, and diagnoses port/startup failures.

```bash
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

./scripts/quickstart.py

```

--------------------------------

### Example homeassistant toolkit calls

Source: https://docs.mindroom.chat/tools/location-commerce-and-home

Shows example calls to the homeassistant toolkit functions: list_entities, get_entity_state, turn_on, set_brightness, activate_scene, and call_service. set_brightness expects a value between 0 and 255, and call_service expects extra service data as a JSON string.

```python
list_entities("light")
get_entity_state("climate.thermostat")
turn_on("light.living_room")
set_brightness("light.living_room", 128)
activate_scene("scene.movie_time")
call_service("notify", "send_message", data='{"message": "Dinner is ready"}')

```

--------------------------------

### Apify Configuration Example

Source: https://docs.mindroom.chat/tools/web-scraping-and-browser

Example configuration for registering an Apify Actor.

```yaml
agents:
  extractor:
    tools:
      - apify:
          actors: apify/rag-web-browser
```

--------------------------------

### Desktop Setup Command

Source: https://docs.mindroom.chat/cli

Usage details for the desktop setup command, which handles login and pairing in a single step. Requires specific controller identifiers and a short-lived code.

```text
 Usage: root desktop setup [OPTIONS]

 Log in when needed, then claim one requester-agent pairing.

╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ *  --code                              TEXT  Short-lived code returned by !desktop     │
│                                              setup.                                    │
│                                              [required]                                │
│ *  --controller-user-id                TEXT  Pinned cloud controller Matrix user.      │
│                                              [required]                                │
│ *  --controller-device-id              TEXT  Pinned cloud controller device.           │
│                                              [required]                                │
│ *  --controller-ed25519                TEXT  Pinned controller fingerprint. [required] │
│    --user-id                           TEXT  Expected Matrix user ID; required for     │
│                                              password login and optional for SSO.      │
│    --homeserver                        TEXT  Matrix homeserver URL; defaults to the    │
│                                              configured MindRoom homeserver.           │
│    --cloudflare-access                       Authenticate Matrix requests              │
│                                              interactively with the local cloudflared  │
│                                              CLI.                                      │
│                                              [env var:                                 │
│                                              MINDROOM_DESKTOP_CLOUDFLARE_ACCESS]       │
│    --matrix-http-headers-file          PATH  Owner-only JSON file of HTTP headers      │
│                                              added to every Matrix request.            │
│                                              [env var:                                 │
│                                              MINDROOM_DESKTOP_MATRIX_HTTP_HEADERS_FIL… │
│    --config                    -c      PATH  MindRoom config path used for runtime     │
│                                              env.                                      │
│    --storage-path              -s      PATH  Desktop bridge state directory.           │
│    --help                      -h            Show this message and exit.               │
╰────────────────────────────────────────────────────────────────────────────────────────╯
```

--------------------------------

### GET /api/knowledge/bases/{base_id}/status

Source: https://docs.mindroom.chat/dashboard

Gets indexing status for a knowledge base.

```APIDOC
## GET /api/knowledge/bases/{base_id}/status

### Description
Gets indexing status for a knowledge base.

### Method
GET

### Endpoint
/api/knowledge/bases/{base_id}/status

### Parameters
#### Path Parameters
- **base_id** (string) - Required - The ID of the knowledge base.
```
Tokens:
Raw