### 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 ``` -------------------------------- ### 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 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. │ ╰────────────────────────────────────────────────────────────────────────────────────────╯ ``` -------------------------------- ### Install MindRoom Desktop Extra Source: https://docs.mindroom.chat/tools/desktop Install the optional desktop dependencies in advance on the computer being controlled. If not installed, `mindroom desktop run` auto-installs the `desktop` extra at startup unless `MINDROOM_NO_AUTO_INSTALL_TOOLS=1` is set. ```bash uv tool install 'mindroom[desktop]' ``` -------------------------------- ### 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). ``` -------------------------------- ### 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 ``` -------------------------------- ### POST /system/instances/{id}/start Source: https://docs.mindroom.chat/deployment/kubernetes Starts a stopped instance. ```APIDOC ## POST /system/instances/{id}/start ### Description Starts a stopped instance. ### Method POST ### Endpoint /system/instances/{id}/start ### Parameters #### Path Parameters - **id** (string) - Required - The instance identifier. ### Request Example No request body required. ### Response #### Success Response (200) No response schema provided. #### Response Example No response example provided. ``` -------------------------------- ### 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"}') ``` -------------------------------- ### 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() ``` -------------------------------- ### brandfetch YAML configuration example Source: https://docs.mindroom.chat/tools/media-and-content Example configuration for enabling the brandfetch tool with search_by_brand enabled and a custom timeout of 10 seconds. ```yaml agents: branding: tools: - brandfetch: enable_search_by_brand: true timeout: 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 ``` -------------------------------- ### Install MindRoom with uv Source: https://docs.mindroom.chat/getting-started Install MindRoom using uv, the recommended package manager. Requires Python 3.12 or higher. ```bash uv tool install mindroom ``` -------------------------------- ### !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 !desktop rotate !desktop disconnect !desktop disconnect confirm ``` -------------------------------- ### 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 ``` -------------------------------- ### Example google_drive function calls Source: https://docs.mindroom.chat/tools/data-and-databases Example calls for listing, searching, reading, downloading, uploading, creating folders, moving, and trashing files. ```python google_drive_list_files() google_drive_search_files("name contains 'budget'") google_drive_read_file("1AbCdEfGhIjKlMnOpQrStUvWxYz") google_drive_download_file("1AbCdEfGhIjKlMnOpQrStUvWxYz") google_drive_upload_file("reports/launch-plan.pdf", folder_id="1FolderId") google_drive_create_folder("Launch", parent_id="1FolderId") google_drive_move_file("1FileId", "1NewFolderId", name="Final plan.pdf") google_drive_trash_file("1OldFileId") ``` -------------------------------- ### Pair Local Install with uvx mindroom connect Source: https://docs.mindroom.chat/deployment/hosted-matrix Pairs this install with the hosted chat by running locally. The pair code is valid for 600 seconds (10 minutes) and is only used to bootstrap local pairing. After successful pairing, provisioning credentials are written to ~/.mindroom/.env unless --no-persist-env is used. ```bash uvx mindroom connect --pair-code ABCD-EFGH ``` -------------------------------- ### SKILL.md format example Source: https://docs.mindroom.chat/skills An example of a SKILL.md file using YAML frontmatter for metadata and OpenClaw compatibility. ```markdown --- name: repo-quick-audit description: Quick repository audit checklist metadata: '{openclaw:{requires:{bins:["git"], env:["GITHUB_TOKEN"]}}}' --- # Repo Quick Audit 1. Check CI status 2. Review open issues ``` -------------------------------- ### Install MindRoom Manually Source: https://docs.mindroom.chat/ Commands to install the MindRoom package using either uv or pip. ```bash # Using uv uv tool install mindroom # Or using pip pip install mindroom ``` -------------------------------- ### config_manager API Usage Examples Source: https://docs.mindroom.chat/tools/agent-orchestration Examples of using get_info, manage_config, manage_agent, and manage_team to interact with the configuration control plane. ```python get_info("available_tools") get_info("tool_details", name="claude_agent") manage_config(operation="inspect", path="/authorization") manage_config( operation="patch", changes=[ {"op": "replace", "path": "/models/default/id", "value": "claude-sonnet-5"}, {"op": "add", "path": "/agents/triage/instructions/-", "value": "Escalate anything urgent."}, ], ) manage_agent( operation="create", agent_name="triage", display_name="Triage", role="Sort incoming requests and hand them to the right specialist.", tools=["duckduckgo", "subagents"], model="default", rooms=["lobby"], ) manage_team( team_name="incident_team", display_name="Incident Team", role="Coordinate incident response across ops and code agents.", agents=["ops", "code"], mode="coordinate", ) ``` -------------------------------- ### Start Sandbox Runner and MindRoom Host Source: https://docs.mindroom.chat/deployment/sandbox-proxy Commands to initialize the sandbox runner container and start the MindRoom application on the host machine using the proxy. ```bash # 1. Start the sandbox runner container export MINDROOM_SANDBOX_PROXY_TOKEN="$(openssl rand -hex 32)" docker run -d \ --name mindroom-sandbox-runner \ -p 127.0.0.1:8766:8766 \ -e MINDROOM_WORKER_BACKEND=static_runner \ -e MINDROOM_SANDBOX_RUNNER_MODE=true \ -e MINDROOM_SANDBOX_PROXY_TOKEN="$MINDROOM_SANDBOX_PROXY_TOKEN" \ -e MINDROOM_STORAGE_PATH=/app/workspace/.mindroom \ ghcr.io/mindroom-ai/mindroom:latest \ /app/run-sandbox-runner.sh # 2. Start MindRoom on the host with proxy config export MINDROOM_WORKER_BACKEND=static_runner export MINDROOM_SANDBOX_PROXY_URL=http://localhost:8766 export MINDROOM_SANDBOX_EXECUTION_MODE=selective export MINDROOM_SANDBOX_PROXY_TOOLS=shell,file,python mindroom run ``` -------------------------------- ### ScrapeGraph Configuration Example Source: https://docs.mindroom.chat/tools/web-scraping-and-browser Example configuration for enabling the searchscraper tool within the agents extractor. ```yaml agents: extractor: tools: - scrapegraph: enable_searchscraper: true ``` -------------------------------- ### Plugin configuration Source: https://docs.mindroom.chat/hooks Example configuration in config.yaml to register the plugin and its settings. ```yaml # config.yaml plugins: - path: ./plugins/location-context settings: dawarich_url: http://dawarich.local ``` -------------------------------- ### Start MindRoom in Standalone Mode Source: https://docs.mindroom.chat/dashboard Run this command to start the MindRoom service and access the dashboard locally at http://localhost:8765. ```bash mindroom run ``` -------------------------------- ### !schedule one-time task examples Source: https://docs.mindroom.chat/chat-commands Examples of one-time scheduled tasks using natural language. ```text !schedule in 5 minutes Check the deployment !schedule tomorrow at 3pm Send the weekly report ``` -------------------------------- ### Install Instance via Helm Source: https://docs.mindroom.chat/deployment/kubernetes Directly install or upgrade a MindRoom instance using Helm. This method is intended for debugging purposes. ```bash helm upgrade --install instance-1 ./cluster/k8s/instance \ --namespace mindroom-instances \ --create-namespace \ --set customer=1 \ --set accountId="your-account-uuid" \ --set baseDomain=mindroom.chat \ --set anthropic_key="your-key" \ --set openrouter_key="your-key" \ --set supabaseUrl="https://your-project.supabase.co" \ --set supabaseAnonKey="your-anon-key" \ --set supabaseServiceKey="your-service-key" ``` -------------------------------- ### !schedule context control examples Source: https://docs.mindroom.chat/chat-commands Examples of controlling context for scheduled runs: 'with no history' or 'without context' for no prior messages, or 'with only the last N messages' to cap context. ```text !schedule Every hour, @ops check deployment health with no history !schedule Daily at 9am, @research summarize AI news with only the last 5 messages ``` -------------------------------- ### Agent Configuration YAML Example Source: https://docs.mindroom.chat/tools/agent-orchestration An example of an agent configuration definition including display name, role, model, and assigned tools. ```yaml agents: builder: display_name: Builder role: Create and maintain MindRoom agents and teams model: sonnet tools: - config_manager ``` -------------------------------- ### 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 ``` -------------------------------- ### 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 ``` -------------------------------- ### Use google_bigquery functions Source: https://docs.mindroom.chat/tools/data-and-databases Example calls to the google_bigquery toolkit functions: list_tables(), describe_table(), and run_sql_query(). The run_sql_query example runs a SQL query to count events by name. ```text list_tables() describe_table("events") run_sql_query("SELECT event_name, COUNT(*) AS total FROM events GROUP BY 1 ORDER BY total DESC LIMIT 20") ``` -------------------------------- ### 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"}) ``` -------------------------------- ### 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 ``` -------------------------------- ### 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 ``` -------------------------------- ### 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 ``` -------------------------------- ### Execute SerpApi Search Functions Source: https://docs.mindroom.chat/tools/web-search Example usage of the search_google and search_youtube functions. ```python search_google("Matrix bridges", num_results=10) search_youtube("Matrix conference talks") ``` -------------------------------- ### 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 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", "

Initial draft

") ``` -------------------------------- ### Browserbase Configuration Source: https://docs.mindroom.chat/tools/web-scraping-and-browser Example configuration for the browserbase tool, specifying content parsing and length limits. ```yaml agents: browser_worker: tools: - browserbase: parse_html: true max_content_length: 20000 ``` -------------------------------- ### 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.") ``` -------------------------------- ### 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 ``` -------------------------------- ### AgentQL Configuration Source: https://docs.mindroom.chat/tools/web-scraping-and-browser Example configuration for the agentql tool, defining the custom query structure. ```yaml agents: extractor: tools: - agentql: agentql_query: | { title links[] } ``` -------------------------------- ### 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} ``` -------------------------------- ### Example reasoning think and analyze calls Source: https://docs.mindroom.chat/tools/execution-and-coding Example calls to the reasoning tool's think and analyze functions. think records an intermediate thought plus an optional next action, while analyze records the result of a prior step and maps next_action onto continue, validate, or final_answer. ```text think( title="Plan the investigation", thought="I should inspect the config and then compare it with the runtime behavior.", action="Read the relevant files.", ) analyze( title="Evaluate the findings", result="The config and runtime behavior match.", analysis="I have enough information to answer clearly.", next_action="final_answer", ) ``` -------------------------------- ### 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 ``` -------------------------------- ### 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/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 ``` -------------------------------- ### Start services with docker compose Source: https://docs.mindroom.chat/deployment/docker Launches the defined MindRoom service in detached mode. ```bash docker compose up -d ``` -------------------------------- ### 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 ``` -------------------------------- ### Reference plugins in config.yaml Source: https://docs.mindroom.chat/plugins Add the installed plugin path to your configuration file to enable it. ```yaml plugins: - path: plugins/ping-hook-plugin ``` -------------------------------- ### 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 ``` -------------------------------- ### Configure openclaw_compat in agents.yaml Source: https://docs.mindroom.chat/tools/agent-orchestration Example configuration for an agent using the openclaw_compat preset within the tools list. ```yaml agents: openclaw: display_name: OpenClawAgent role: OpenClaw-style personal assistant with a file-first workspace model: opus include_default_tools: false learning: false memory_backend: file context_files: - SOUL.md - AGENTS.md - USER.md - IDENTITY.md - TOOLS.md - HEARTBEAT.md tools: - openclaw_compat - python ``` -------------------------------- ### Perform Trello operations Source: https://docs.mindroom.chat/tools/project-management Examples of listing boards, retrieving board lists, and creating a new card. ```python list_boards(board_filter="open") get_board_lists("BOARD_ID") create_card("BOARD_ID", "To Do", "Write docs", "Draft the new tool page") ``` -------------------------------- ### 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. ``` -------------------------------- ### GET /api/credentials/{service}/api-key Source: https://docs.mindroom.chat/dashboard Gets a masked API key for a service. ```APIDOC ## GET /api/credentials/{service}/api-key ### Description Gets a masked API key for a service. ### Method GET ### Endpoint /api/credentials/{service}/api-key ### 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) - Masked API key ``` -------------------------------- ### Show configuration Source: https://docs.mindroom.chat/cli Displays the current configuration file with options for raw output or custom paths. ```bash # Show config with syntax highlighting mindroom config show # Print raw YAML (useful for piping) mindroom config show --raw # Show config at a specific path mindroom config show --path /custom/path/config.yaml ``` -------------------------------- ### Split configuration into multiple files Source: https://docs.mindroom.chat/configuration Example of a main config.yaml using include tags to reference agent definitions and model configurations. ```yaml # config.yaml agents: !include_dir_merge_named agents/ models: !include models.yaml defaults: tools: [scheduler] markdown: true ``` ```yaml # agents/researcher.yaml researcher: display_name: Researcher role: Deep research and analysis model: default tools: !include _shared/web_tools.yaml instructions: - !include_text ../prompts/researcher.md ``` ```yaml # agents/_shared/web_tools.yaml - duckduckgo - website - browser ``` -------------------------------- ### Install plugin dependencies manually with pip Source: https://docs.mindroom.chat/plugins Plugin tool dependencies are not auto-installed; users must install them manually. This command installs the required packages listed in the plugin's dependencies field. ```bash pip install openviking-client aiohttp ``` -------------------------------- ### Initialize and Connect MindRoom with uvx Source: https://docs.mindroom.chat/ Commands to initialize the configuration, set environment variables, pair with the chat interface, and start the MindRoom agent. ```bash # Create ~/.mindroom/config.yaml and ~/.mindroom/.env with hosted defaults uvx mindroom config init # Add model auth (e.g. OPENAI_API_KEY or ANTHROPIC_API_KEY) $EDITOR ~/.mindroom/.env # Generate pair code in https://chat.mindroom.chat: # Settings -> Local MindRoom -> Generate Pair Code uvx mindroom connect --pair-code ABCD-EFGH # Start MindRoom uvx mindroom run ``` -------------------------------- ### Manage Todo Items and Templates Source: https://docs.mindroom.chat/tools/project-management Examples of planning tasks, adding individual items, listing status, updating items, and applying templates. ```python plan("[high] Inspect issue\nWrite failing test\nImplement fix") add_todo("Run focused regression test", depends_on="a1b2c3d4", priority="high") list_todos(show_all=True) update_todo("a1b2c3d4", status="done") apply_template("mindroom-dev", {"ISSUE_REF": "ISSUE-123", "REPO": "mindroom"}) ``` -------------------------------- ### GET /api/skills/{skill_name} Source: https://docs.mindroom.chat/dashboard Gets skill detail including content, origin, and edit status. ```APIDOC ## GET /api/skills/{skill_name} ### Description Gets skill detail including content, origin, and edit status. ### Method GET ### Endpoint /api/skills/{skill_name} ### Parameters #### Path Parameters - **skill_name** (string) - Required - The name of the skill. ``` -------------------------------- ### Initialize configuration with specific providers Source: https://docs.mindroom.chat/getting-started Initializes MindRoom with a specific model provider preset. ```bash # Use Anthropic Claude uvx mindroom config init --provider anthropic # Use Azure OpenAI uvx mindroom config init --provider azure # Use a Codex CLI ChatGPT login uvx mindroom config init --provider codex # Use local Ollama uvx mindroom config init --provider ollama # Use local llama.cpp through its OpenAI-compatible server uvx mindroom config init --provider llama.cpp # Use Vertex AI Claude (Google Cloud) uvx mindroom config init --provider vertexai_claude ``` -------------------------------- ### Minimal tool registration with @register_tool_with_metadata Source: https://docs.mindroom.chat/plugins Registers a simple greeter tool using @register_tool_with_metadata with setup_type=SetupType.NONE. The tool returns a GreeterTools Toolkit instance with a greet method. This is the minimal example for creating a plugin tool. ```python from __future__ import annotations from typing import TYPE_CHECKING from mindroom.tool_system.declarations import ( SetupType, ToolCategory, ToolStatus, ) from mindroom.tool_system.registration import register_tool_with_metadata if TYPE_CHECKING: from agno.tools import Toolkit @register_tool_with_metadata( name="greeter", display_name="Greeter", description="A simple greeting tool", category=ToolCategory.DEVELOPMENT, status=ToolStatus.AVAILABLE, setup_type=SetupType.NONE, ) def greeter_tools() -> type[Toolkit]: from agno.tools import Toolkit class GreeterTools(Toolkit): def __init__(self) -> None: super().__init__(name="greeter", tools=[self.greet]) def greet(self, name: str) -> str: """Greet someone by name.""" return f"Hello, {name}!" return GreeterTools ``` -------------------------------- ### Usage examples for thread_tags functions Source: https://docs.mindroom.chat/tools/matrix-and-attachments Examples of calling tag_thread, untag_thread, and list_thread_tags with various parameters. ```python tag_thread("blocked") untag_thread("blocked") list_thread_tags(thread_id="$threadRootEvent") list_thread_tags(exclude_tag="resolved", include_untagged=True) ``` -------------------------------- ### Run MindRoom Source: https://docs.mindroom.chat/getting-started Starts MindRoom, which connects to the Matrix homeserver, creates agent users, creates and joins rooms, and listens for messages. ```bash mindroom run ``` -------------------------------- ### Initialize Bedrock configuration Source: https://docs.mindroom.chat/configuration/models Command to generate a starter configuration for the Bedrock Claude provider. ```bash mindroom config init --provider bedrock_claude ``` -------------------------------- ### Basic Knowledge Base Configuration Source: https://docs.mindroom.chat/knowledge An example configuration block for a knowledge base named 'my_docs', defining its description, mode, path, and chunking parameters. ```yaml knowledge_bases: my_docs: description: Product documentation, support notes, and internal operating procedures mode: semantic # "semantic" builds a vector search index; "files" skips embeddings path: ./knowledge_docs/my_docs # Folder containing documents watch: false # Direct external edits require reindex; API mutations still schedule refresh require_content_before_publish: false # Keep a cold semantic index initializing until a managed file exists chunk_size: 5000 # Max characters per chunk chunk_overlap: 0 # Overlap between adjacent chunks ``` -------------------------------- ### MindRoom run command help output Source: https://docs.mindroom.chat/cli Shows the usage and options for the 'run' command. This command starts the multi-agent bot system, creating accounts, rooms, and managing memberships. It can optionally start the bundled dashboard/API server. Options include --log-level, --config, --storage-path, --api/--no-api, --api-port, --api-host, and --help. ```text Usage: root run [OPTIONS] Run the mindroom multi-agent system. This command starts the multi-agent bot system which automatically: - Creates all necessary user and agent accounts - Creates all rooms defined in config.yaml - Manages agent room memberships - Starts the bundled dashboard/API server (disable with --no-api) ╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ │ --log-level -l TEXT Set the logging level (DEBUG, INFO, WARNING, │ │ ERROR) │ │ [env var: LOG_LEVEL] │ │ [default: INFO] │ │ --config -c PATH Use this config file path. Defaults the │ │ storage location to the selected config │ │ directory unless --storage-path is set. │ │ --storage-path -s PATH Base directory for persistent MindRoom data │ │ (state, sessions, tracking) │ │ --api --no-api Start the bundled dashboard/API server │ │ alongside the bot │ │ [default: api] │ │ --api-port INTEGER Port for the bundled dashboard/API server │ │ [default: 8765] │ │ --api-host TEXT Host for the bundled dashboard/API server │ │ [default: 0.0.0.0] │ │ --help -h Show this message and exit. │ ╰────────────────────────────────────────────────────────────────────────────────────────╯ ``` -------------------------------- ### Initialize and run MindRoom with hosted Matrix Source: https://docs.mindroom.chat/deployment Creates default config files, prompts to edit .env, connects with a pair code, and runs MindRoom. Pair code generated in chat.mindroom.chat under Settings -> Local MindRoom. ```bash # 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 ``` -------------------------------- ### brandfetch usage examples for search_by_identifier and search_by_brand Source: https://docs.mindroom.chat/tools/media-and-content Example calls to the brandfetch methods: search_by_identifier with a domain and search_by_brand with a brand name. ```python search_by_identifier("openai.com") search_by_brand("OpenAI") ``` -------------------------------- ### Set up local Matrix and MindRoom Chat with host-installed MindRoom Source: https://docs.mindroom.chat/deployment Sets up local Matrix and MindRoom Chat using a host-installed MindRoom runtime on Linux/macOS, then runs MindRoom with local storage. ```bash mindroom local-stack-setup --synapse-dir /path/to/mindroom-stack/local/matrix mindroom run --storage-path ./mindroom_data ``` -------------------------------- ### !schedule recurring task examples Source: https://docs.mindroom.chat/chat-commands Examples of recurring scheduled tasks using natural language with @agent or @team mentions. ```text !schedule Every hour, @shell check server status !schedule Daily at 9am, @finance market report !schedule Weekly on Friday, @analyst prepare weekly summary ``` -------------------------------- ### CLI Help and Command Overview Source: https://docs.mindroom.chat/cli Displays the root help menu, including available commands and global options for the MindRoom CLI. ```text Usage: root [OPTIONS] COMMAND [ARGS]... AI agents that live in Matrix and work everywhere via bridges. Quick start: mindroom config init Create a starter config mindroom run Start the system ╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ │ --install-completion Install completion for the current shell. │ │ --show-completion Show completion for the current shell, to copy it or │ │ customize the installation. │ │ --help -h Show this message and exit. │ ╰────────────────────────────────────────────────────────────────────────────────────────╯ ╭─ Commands ─────────────────────────────────────────────────────────────────────────────╮ │ version Show the current version of Mindroom. │ │ run Run the mindroom multi-agent system. │ │ doctor Check your environment for common issues. │ │ connect Pair this local MindRoom install with the hosted provisioning │ │ service. │ │ local-stack-setup Start local Synapse + MindRoom Chat using Docker only. │ │ config Manage MindRoom configuration files. │ │ plugins Validate and vendor external MindRoom plugins. │ │ desktop Connect allowlisted local applications to cloud MindRoom over │ │ Matrix E2EE. │ │ avatars Generate and sync managed avatar assets. │ │ threads Export Matrix threads to local files. │ │ journal Inspect and rebind the durable event journal. │ │ service Install and manage MindRoom as a background user service. │ │ trigger Send signed external triggers. │ ╰────────────────────────────────────────────────────────────────────────────────────────╯ ``` -------------------------------- ### website read_url example Source: https://docs.mindroom.chat/tools/web-scraping-and-browser Example of using the website tool's read_url function on a URL, returning JSON-serialized Document objects. ```python read_url("https://docs.mindroom.chat") ``` -------------------------------- ### Configure Production Runtime Values Source: https://docs.mindroom.chat/deployment/kubernetes Example configuration for production environments, pointing to existing ConfigMaps, storage claims, and secrets. ```yaml config: create: false existingConfigMap: mindroom-config key: config.yaml storage: create: false existingClaim: mindroom-data matrix: homeserverUrl: http://matrix.example.svc.cluster.local:8008 serverName: example.com registrationToken: existingSecret: mindroom-secrets key: MATRIX_REGISTRATION_TOKEN env: envFrom: - secretRef: name: mindroom-secrets workers: backend: kubernetes sandbox: proxyToken: existingSecret: mindroom-sandbox-proxy key: MINDROOM_SANDBOX_PROXY_TOKEN ``` -------------------------------- ### Execute Docker operations Source: https://docs.mindroom.chat/tools/execution-and-coding Example calls for listing containers, running a new container, retrieving logs, and listing images or networks. ```python list_containers() run_container("postgres:16", detach=True, environment={"POSTGRES_PASSWORD": "example"}) get_container_logs("postgres", tail=50) list_images() list_networks() ``` -------------------------------- ### Install a global skill Source: https://docs.mindroom.chat/openclaw Commands to create the global skills directory and copy a skill from a workspace to the user's global skills path. ```bash mkdir -p ~/.mindroom/skills cp -r /path/to/openclaw-workspace/skills/transcribe ~/.mindroom/skills/ ``` -------------------------------- ### crawl4ai crawl function call example Source: https://docs.mindroom.chat/tools/web-scraping-and-browser Example of calling the crawl4ai crawl function with a URL and a search query for BM25-based content filtering. ```python crawl("https://matrix.org/blog/", search_query="bridges and federation") ``` -------------------------------- ### Configure Semantic Knowledge Base Source: https://docs.mindroom.chat/knowledge Example configuration for a semantic knowledge base using ChromaDB and assigning it to an agent. ```yaml knowledge_bases: docs: description: Product documentation, support notes, and internal operating procedures mode: semantic path: ./knowledge_docs watch: false chunk_size: 5000 chunk_overlap: 0 agents: assistant: display_name: Assistant role: A helpful assistant with access to our docs knowledge_bases: [docs] ``` -------------------------------- ### Cartesia voice functions usage example Source: https://docs.mindroom.chat/tools/ai-and-generation Example calls to list_voices(), localize_voice(), and text_to_speech() showing how to list voices, create a localized voice, and generate speech. ```python list_voices() localize_voice( name="French Support Voice", description="Warm and clear support voice.", language="fr", original_speaker_gender="female", ) text_to_speech("Deployment complete.") ``` -------------------------------- ### Deploy Platform with Helm Source: https://docs.mindroom.chat/deployment/kubernetes Commands to initialize the values file and deploy the platform chart to the mindroom-staging namespace. ```bash # Create values file from example cp cluster/k8s/platform/values-staging.example.yaml cluster/k8s/platform/values-staging.yaml # Edit with your configuration helm upgrade --install platform ./cluster/k8s/platform \ -f ./cluster/k8s/platform/values-staging.yaml \ --namespace mindroom-staging ``` -------------------------------- ### Example tool arguments for create_trigger Source: https://docs.mindroom.chat/external-triggers Example tool arguments for calling external_trigger_manager.create_trigger. Shows the expected fields (trigger_id, public_key, key_id, description, allowed_kinds, replay_window_seconds, max_body_bytes). ```json { "trigger_id": "campground", "public_key": "BASE64_PUBLIC_KEY_FROM_KEYGEN", "key_id": "campground-main", "description": "Campground availability watcher", "allowed_kinds": ["campground.availability"], "replay_window_seconds": 300, "max_body_bytes": 65536 } ``` -------------------------------- ### GET /api/ready Source: https://docs.mindroom.chat/dashboard Returns ready status when the orchestrator has finished startup. Returns 503 with phase and detail otherwise. ```APIDOC ## GET /api/ready ### Description Returns ready status when the orchestrator has finished startup. Returns 503 with phase and detail otherwise. ### Method GET ### Endpoint /api/ready ### Response #### Success Response (200) - **status** (string) - "ready" n #### Error Response (503) - **status** (string) - The current phase (idle, starting, ready, failed). n- **detail** (string) - Detail message. #### Response Example { "status": "ready" n} ``` -------------------------------- ### !help command usage Source: https://docs.mindroom.chat/chat-commands Displays available commands or detailed help on a specific topic. Accepts optional topic arguments such as schedule, config, or cancel_schedule. ```text !help !help schedule !help config !help cancel_schedule !help edit_schedule ``` -------------------------------- ### Example template directory structure Source: https://docs.mindroom.chat/configuration/agents Shows the file layout for the template directory referenced in the agent configuration. ```text mind_template/ ├── SOUL.md ├── AGENTS.md ├── USER.md ├── IDENTITY.md ├── TOOLS.md ├── HEARTBEAT.md ├── MEMORY.md └── memory/ ``` -------------------------------- ### Example method calls for financial_datasets_api Source: https://docs.mindroom.chat/tools/data-and-databases Example Python calls to financial_datasets_api methods: search_tickers, get_company_info, get_stock_prices, get_income_statements, and get_news. These demonstrate typical usage for retrieving financial data. ```python search_tickers("cloud software", limit=5) get_company_info("MSFT") get_stock_prices("AAPL", interval="1d", limit=30) get_income_statements("NVDA", period="quarterly", limit=4) get_news("TSLA", limit=10) ``` -------------------------------- ### Bootstrap local Synapse and MindRoom Chat with Docker Source: https://docs.mindroom.chat/getting-started Helper command to set up a local Matrix homeserver and MindRoom Chat container using Docker. Requires a path to the mindroom-stack local matrix directory. ```bash mindroom local-stack-setup --synapse-dir /path/to/mindroom-stack/local/matrix ```