Library / SDK
thetahealth/mirobody avatar
thetahealth/mirobody

Mirobody: a self-hosted health engine that ships its own repair container, demo data and floor constraints

The AI-native health data engine — collect, standardize, and reason over labs, wearables & genomics.

1,524 stars261 forksPythonApache-2.0

At a glance

What is it?
A Python health data engine that maps lab names onto LOINC codes offline and serves an agent over the coded record. The build and compose files carry three post-mortems in comments, and the demo account is seeded on by default.
Who is it for?
Mirobody is built for someone who wants their lab reports, wearable exports and genetic files in one record with every number traceable to a page, and who will run it on their own hardware with a model key of their choosing. Read three defaults before you do.
Can I use it commercially?
Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 2 days ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • thetahealth/mirobody1,524 ★ · +226
Star history
Repository2026-09-112026-11-15
thetahealth/mirobody1.3k1.5k

226 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

A container that runs as root before the app does

The compose file carries a repair step for a regression that is worth reading in full. Uploads written by 1.5.2 belong to root, because that release ran the app as root, while the current image runs as uid 10001. The new user could read those files but could not add one, so every upload failed after upgrading. The fix is a separate service named mirobody_init that runs before the app, with user set to 0:0, restart set to no, network_mode set to none and its healthcheck disabled. It issues one find over the upload directory that chowns anything not already owned by the app user, skips files it already owns, and prints a warning to standard error rather than failing when the mount refuses the change, which is the NFS root_squash case. It runs on every start, so a restored 1.5.2 archive is covered as well.

The build once published a 22-byte package

The Dockerfile records a second failure mode, and the fix is visible as two extra lines. The install step leaves build/lib holding a generated version stub that is newer than the copied source. Because the stub has the newer timestamp, the next layer's copy of the real source is skipped, and the image ships a 22-byte package: import mirobody succeeds, but mirobody.resolve raises ImportError. The remedy is to delete build and the egg-info directory, then reinstall the project alone with --no-deps and --force-reinstall. The stub itself is written by a printf that emits only a __version__ line, with the version coming from a build argument that defaults to 1.5.3.dev0. A layer ordering problem turned into a package that looked importable and was not.

A restart does not read .env a second time

Two commands are the whole install path:

bash
git clone --depth 1 https://github.com/thetahealth/mirobody.git && cd mirobody
OPENROUTER_API_KEY=sk-or-... ./deploy.sh     # Postgres, server and worker → http://localhost:18060

Docker is the only requirement, with no Python, Node.js, GPU, Git LFS or even Git. deploy.sh writes the secrets and your key into .env and pulls the prebuilt image, falling back to building from the checkout when the pull fails. It stops and names the fix when a port is taken or when another Mirobody stack is already running under the folder's name, because the image expects its own Postgres beside it, so docker run on its own is not a way in. The operational detail that catches people: a key added after first start goes into .env and needs docker compose up -d, because a restart does not read .env again. Postgres listens on 18062 bound to loopback, and its password falls back to a literal placeholder string if you never set one.

PyPI carries the library, the checkout carries the platform

The requirements file is one line, and its comment explains the whole packaging decision:

code
-e .[app]

That is the full platform, and it is the only thing that installs the app extra, which is the point: the Docker application mounts the checkout and pip-installs from it, so PyPI is never a deployment path and the app extra never asks anyone to choose a backend. A bare pip install of the package is the library instead, covering the translate stage, namely resolve, units and lexical work, on numpy alone. Adding the parse extra covers the collect stage's single-file surface. The comment defers to pyproject.toml for why there are only those two extras. So the published artifact is deliberately small, and everything that needs the heavy numeric stack comes from the repository.

Python 3.12 is a syntax floor, and the build backend is custom

The packaging metadata argues its own cases in comments. The 3.12 floor is stated as a hard requirement rather than a preference, because the codebase uses PEP 701 f-strings with nested same-type quotes, which is a SyntaxError on 3.11, so the package cannot even be imported there. The build backend is not plain setuptools: build-backend points at a wrapper in scripts, described as a thin layer that drops checkout-only test modules from the built distribution, with test_skills.py deliberately retained as public release evidence. The stated reason is that exclude-package-data cannot make that split, because test_*.py files are package code rather than data. One more comment is a maintenance instruction rather than a fact: the PyPI description line must be kept in lockstep with the README's H1 tagline.

The demo account is seeded on, with a fixed code

A self-hosted health deployment ships with someone else's health data in it by default. SEED_DEMO_DATA is on, and the sign-in page offers [email protected] with the code 111111 on the email-code tab. Two accounts already hold 2,019 readings: yours, and [email protected], who shares her record with you view-only. The demo directory supplies four files the seed leaves out, and they are split by owner rather than pooled, so the lab PDF and one CSV are yours while the report photo and the spreadsheet belong to her and must be uploaded while signed in as her. There is also a hosted demo at chat.mirobody.ai with no sign-up. For a system holding medical records, that default is the first thing to turn off before the service is reachable by anything but yourself.

One function is the entire cross-account access path

Sharing is built as a care circle, and the design keeps the surface small on purpose. It is invite-only and off by default, and a single function named resolve_subject is described as the only way an account reaches a record that is not its own. Every other path, the seed data, the sharing UI, the agent tools, funnels through that one gate, so the review question becomes narrow: read resolve_subject and you know where a record can go. Per-user request visibility has a parallel shape, with administrators able to limit regular users to their own linked account. The same tools the agent calls are also served at an /mcp endpoint, gated per user, so an MCP client is a second front door onto the same data with its own authorisation surface.

The vocabulary picks the code, not the model

The translate stage is described as offline and deterministic: one name to one code, one unit to UCUM. A1c, HbA1c and Glycated Hemoglobin become the same test under LOINC, and a complaint maps through ICPC-3 so that one word and its Chinese equivalent settle onto one entry. Where a term cannot be placed, the engine says so and keeps the original words instead of guessing. The journal makes the split explicit. Typing `headache since last night, BP 150/95, no fever, metformin 500 mg morning and evening` into the record produces one coded complaint, two coded readings and a medication entry, and no fever is held out of the record rather than logged as a fever. The model splits the sentence and types each part; the codes come from the vocabulary. That is tested against real reports in English, Chinese, Japanese and Russian, and the repository carries a Chinese README alongside the English one. Genetics is scoped the same way. An export or a VCF can be asked about by rsID, by gene or by region, and a drug question is answered with CPIC coverage rather than with a phenotype or a suggested change of medication.

Editorial conclusion

Mirobody is built for someone who wants their lab reports, wearable exports and genetic files in one record with every number traceable to a page, and who will run it on their own hardware with a model key of their choosing. Read three defaults before you do. SEED_DEMO_DATA is on, so a fresh deployment already holds two accounts and 2,019 readings behind a fixed six-digit code. The compose file falls back to a literal placeholder Postgres password if you never set one, so put a real PG_PASSWORD in .env even though the database port binds to loopback. And the API serves every tool again at /mcp, gated per user, which is a second surface to review before exposing anything.

Frequently asked questions

How do I run Mirobody on my own machine?

Clone the repository and run deploy.sh with a model key set, for example OPENROUTER_API_KEY. Docker is the only requirement, with no Python, Node.js, GPU, Git LFS or Git needed, and the server comes up on port 18060 beside its own Postgres on 18062.

Which AI providers does Mirobody support?

Any one of OpenRouter, OpenAI, Gemini, Anthropic, DeepSeek, DashScope, or any OpenAI-compatible gateway reached through a PROVIDER_BASE_URL variable runs every surface. The config file names the variable and never the secret, and mirobody doctor prints what each surface selected.

What health data sources can Mirobody read?

Garmin, Oura and Whoop connect directly, Apple Health data comes along, and 23 file types including PDFs, phone photos, spreadsheets and exports are read by kind. Genetic files can be a 23andMe, AncestryDNA, MyHeritage, FTDNA or WeGene export, or a VCF.

Does Mirobody ship with demo data enabled?

Yes. SEED_DEMO_DATA is on by default, and two accounts already hold 2,019 readings: [email protected] with the code 111111, and [email protected], whose record is shared view-only. Four further files sit in the demo upload folder, split so two belong to each account.

How does Mirobody stop an AI model inventing medical codes?

The translate stage runs offline and deterministic, mapping names onto LOINC for tests, UCUM for units and ICPC-3 for complaints, and an unplaceable term is reported rather than guessed. The model splits a journal sentence and types each part, but the codes themselves come from the vocabulary.

Official sources

  1. License: Apache-2.0
  2. Project website
  3. README
  4. Releases
  5. thetahealth/mirobody on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/thetahealth-mirobody.svg)](https://hysenlabs.com/projects/thetahealth-mirobody)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/thetahealth-mirobody.svg)](https://hysenlabs.com/projects/thetahealth-mirobody)

Was this useful?