Quickstart

One path from an empty directory to a signed-in Mirobody: clone, run ./deploy.sh, open the browser, sign in with a demo account, then add an LLM key. Everything runs in Docker, so you do not need Python or Node on the host for this page.

Note

For a local Python development setup, or for pip install mirobody, see Installation.

Prerequisites

Requirement	Why
Docker + Docker Compose	deploy.sh builds one image and starts four containers.
Git	To clone the repository.
Git LFS	Terminology and indicator resources under mirobody/res/ are LFS objects. Without LFS you get pointer files and startup fails.

1. Clone the repository

Install Git LFS before cloning: apt install git-lfs, brew install git-lfs, or bundled with Git for Windows.

git lfs install          # once per machine
git clone https://github.com/thetahealth/mirobody.git
cd mirobody

2. Run the deploy script

./deploy.sh

The script does four things:

Writes .env

Sets ENV=localdb and generates a 32-character CONFIG_ENCRYPTION_KEY. Existing files are left alone.

Writes config.localdb.yaml

Your override file, seeded with a random JWT_KEY, the demo login codes, and commented-out placeholders for the LLM keys.

Builds the image

An Ubuntu 24.04 image with a Python virtualenv and Node.js. If hub.docker.com is unreachable the script falls back to the docker.1ms.run mirror, and npm is pointed at registry.npmmirror.com.

Starts the stack

docker compose up -d, then tails the logs in the foreground. Four containers come up: pg (18082), redis (18089), mirobody (18080), and mirobody_worker.

Tip

The script ends on docker compose logs -f, so it does not return. Press Ctrl-C to detach (the containers keep running), or open a second terminal for the commands below.

3. Open the web client

Open http://localhost:18080. The engine serves a prebuilt web client from the frontend/ directory next to the process; it lives outside the Python package on purpose, so a wheel ships the engine rather than 8 MB of JavaScript.

4. Sign in

deploy.sh writes three predefined accounts into config.localdb.yaml. Use any of them, with the code as the verification code:

demo1@mirobody.ai
777777

Caution

Which accounts work depends on how you started the server, and the two paths disagree. config.{env}.yaml replaces a top-level key rather than merging into it, so the block deploy.sh generates overrides the template’s:

Started with	Accounts	Code
./deploy.sh (this page)	demo1@mirobody.ai · demo2@ · demo3@	777777
your own config, no EMAIL_PREDEFINE_CODES override	exp1@mirobody.ai · exp2@ · exp3@	111111

The server prints the accounts it actually accepted at startup; trust that over any document.

Caution

These codes are public and are meant for a local run. Before you expose the server to a network, configure real email or OAuth sign-in and turn the predefined codes off.

Deleting the block from config.localdb.yaml is not enough: the config.yaml template carries its own predefined accounts (exp1@ … exp3@), and it loads first. Override the key with an empty value instead:

config.localdb.yaml

EMAIL_PREDEFINE_CODES:

5. Add an LLM key

You are signed in, but the agent has no model to call yet. Edit config.localdb.yaml and set at least one key:

config.localdb.yaml

# Pick whichever provider you have a key for. One is enough to start.
OPENROUTER_API_KEY: 'sk-or-...'
# GOOGLE_API_KEY: 'AIza...'
# OPENAI_API_KEY: 'sk-...'

Then restart the two application containers:

docker compose restart mirobody mirobody_worker

Note

On the next startup the engine rewrites that value in place as ciphertext: any key whose name matches _KEY, _PASSWORD, _PASS, _PWD, _SECRET, _SK or _TOKEN is encrypted with the CONFIG_ENCRYPTION_KEY from .env. That is expected; do not paste the plaintext back. See Configuration.

Which models each agent may use is set per agent under PROVIDERS_DEEP and PROVIDERS_BASE; the defaults in config.yaml already reference the key names above.

The embedding key and zero indicators

An LLM key is not enough. The worker’s indicator sync embeds indicator names to standardize them, and that is a different key:

config.localdb.yaml

EMBEDDING_PROVIDER: gemini      # the default
GOOGLE_API_KEY: 'AIza...'       # what `gemini` needs
# EMBEDDING_PROVIDER: qwen      # the other supported provider
# DASHSCOPE_API_KEY: 'sk-...'

With only an OpenRouter key, chat works but Health indicators stays 0: the embedding call fails in the worker, and it fails quietly. docker compose logs mirobody_worker is where it says so.

6. Verify the install

# All four containers up?
docker compose ps

# Liveness — returns JSON with the service name, version, and counts of
# tools, resources and agents that were discovered at startup.
curl http://localhost:18080/api/health

# MCP discovery — JSON-RPC 2.0 over POST, lists the registered tools.
curl -X POST http://localhost:18080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

If /api/health reports "tools": 0, the tool directories were not scanned; check MCP_TOOL_DIRS and the startup log (docker compose logs mirobody).

Next steps

Configuration

The three config layers, the key groups, and what is encrypted.

→

Installation

Local Python development, the PyPI package, and the repository layout.

→

Architecture

How the server, worker, agents and Pulse fit together.

→

Mirobody MCP Server

Point Claude Desktop, Cursor or any MCP client at this server.

→