Self-Host Mirobody

Mirobody runs anywhere Python or Docker runs: a laptop, an on-premises server or a cloud VM. The engine is open source under Apache 2.0 at thetahealth/mirobody, and the data it holds stays in a Postgres you operate. What Mirobody is, and how self-hosting compares with Mirobody Cloud, is on the overview.

Ways to run it

Pick the row that matches what you want; the three are alternatives, not steps.

You want	Path	Needs	Model key
Names and units resolved in your own code	The library	Python	none
The whole product running, with demo data in it	The Docker stack	Git, Docker with Compose	one for model features
To change the code and see the result	A source checkout	Python and a Postgres with pgvector	one for model features

The Docker stack is three containers: Postgres with pgvector, the server and the background worker. It serves the bundled web client at .

First local result

With Git and Docker Compose installed, run the local demo and check its seeded readings. Model features require a supported key in .env; the sample readings are available without one.

Start the demo

Clone the engine and start the stack. The script pulls the application image and creates demo accounts and example readings, then follows the service logs.

git clone --depth 1 https://github.com/thetahealth/mirobody.git && cd mirobody
./deploy.sh

Check the services

When the script reports Up, keep that terminal open. In another terminal, run these commands from the engine checkout:

docker compose ps
curl -fsS http://localhost:18060/api/health
docker compose exec mirobody mirobody doctor

The mirobody service should become healthy, and the health response includes version and agent. The last command checks model features inside the container. If you add a model key to .env after startup, run docker compose up -d; docker compose restart does not re-read .env.

Inspect the readings

Open , sign in as you@mirobody.ai with code 111111, then open Data. The seeded readings should appear there. The Quickstart also covers demo upload files and the other run modes.

For real records, apply the settings in Deploy on a Server before the first start. After running the demo, follow the existing-demo path to start with clean data volumes. Self-hosting keeps the stored record in the Postgres and file storage you operate. Extraction and agent answers send data to whichever model provider you configure; review that provider’s handling of health data before enabling those features.

Where the three stages live

The package is organized around the same three stages as this documentation.

Collect, Translate, Agent: three stages from left to right — A reading moves through collection, standardization, and agent access.

Stage	Package	Pages
① Collect	`mirobody/collect/`	Device Providers, Apple Health, File Processing
② Translate	`mirobody/engine/`, `mirobody/translate/`	Standardization, Device Crosswalk
③ Agent	`mirobody/agent/`	The Agent, Health-Data Tools, MCP Integration

How a single reading passes through all three is described in The Pipeline; the directory map is Repository Layout.

What a deployment serves

Surface	Address	Used by
Web client	`/`	People: documents and readings at `/data`, the agent at `/ask`, and care-circle sharing
HTTP API	`/api/*`	Your own application; begin with the local HTTP API guide
MCP endpoint	`/mcp`	Claude Desktop, Cursor, or an agent loop of your own; see MCP Integration

A self-hosted engine does not serve the Cloud /v1 API. The Cloud tab documents that surface; the routes above are the engine’s own.

Next steps

Quickstart

Install the library, bring up the stack, or run a checkout.

Configuration

The model key, the configuration files, and the settings a deployment changes.

HTTP API

Get a local token, write a reading, and read it back.

Walkthrough

The running stack in four scenes, with the demo record.

Deploy on a Server

Production posture, secrets, HTTPS and a deployment check.

Upgrade a Deployment

Back up, review a release, upgrade and verify the running stack.

Verify and Restore a Backup

Rehearse a restore and recover Postgres and local uploads.

When a deployment does not come up, Troubleshooting lists the common causes and their fixes.

Contributing

The highest-leverage contribution is a term the resolver gets wrong. Run mirobody resolve "<term>"; if the answer is wrong or empty, report it, or add a row to together with a case in . The coverage score is the review. A development checkout installs the test extra and runs the suite and the import contracts:

pip install -e '.[test]' && pytest -q && lint-imports

The full contributor workflow is in , and the test layout in . Public benchmarks under benchmarks/ run from a clone with no private data: python -m unittest benchmarks.health_records.test_cases (13 synthetic readings and 26 complaint phrases in five languages, checked against their LOINC/UCUM and ICPC-3 codes) and python -m unittest discover -s benchmarks/genomics -p 'test_*.py' (13 public 1000 Genomes calls in ten file shapes). See and .

GitHub repository

Source code, issues and pull requests.

Report a problem

A report that parses incorrectly makes a valuable issue; attach a de-identified sample.

Security reports go through a private advisory, not a public issue; see .

​Ways to run it

​First local result

​Where the three stages live

​What a deployment serves

​Next steps