# Mirobody

> Self-host Mirobody, the open-source health data engine, and use it from an agent. Use when the user wants to run a personal or family health record on their own machine, bring lab reports and wearables (Apple Health, Garmin, Oura, WHOOP) into one place an AI can read, expose their health data to Claude Code, Codex, Cursor, Claude Desktop or another agent over MCP, or operate a stack that is already running (model key, upgrade, backup, ports). Docker is the only requirement; one model API key runs every surface, or no key with every model on the same machine on llama.cpp.

- Skill: `thetahealth/mirobody` (Agent Skill)
- Install (CLI): `npx get-skill add thetahealth/mirobody`
- Raw SKILL.md: https://api.skillmd.com/api/skills/thetahealth/mirobody/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- License: Apache-2.0
- Author: thetahealth (https://skillmd.com/u/thetahealth)
- Updated: 2026-11-18
- Page: https://skillmd.com/skills/thetahealth/mirobody

---


# Mirobody

Mirobody reads a person's health data from any source (lab PDFs, report
photos, spreadsheets, device exports, genotype files, a typed sentence),
settles every value onto one standard code, and answers questions over that
record with each number traced to the file it came from. It runs in Docker on
the user's machine, on a model key they choose, or with every model on that
machine through llama.cpp (`llama-server`), its local model runtime. With a
key, questions and documents go to that vendor; with the local models they
stay on the machine. Either way the record stays in the user's own Postgres,
and a wearable vendor is called only once one is linked.

This skill gets a stack running and connects an agent to it. The sibling
`standardize-health-data` skill covers the library without Docker: it turns raw
files into coded rows and explains a report only from resolved evidence.

## Agent contract

- **The model key comes from the user.** Ask for it, or for which provider they
  use, or whether they want every model on this machine instead (llama.cpp:
  the default small pair needs 16 GB of memory and no GPU, and on a CPU alone
  a first answer takes minutes: 2–3 on an Apple-silicon laptop's cores, up to about 15 on a 4-vCPU x86 server; the large size needs about 20 GB;
  `docs/local-models.md`). Never invent a key, never
  print one back, never paste it into a chat reply. Write it into `.env` and
  nowhere else, or leave it to the first-run page `./deploy.sh` links.
- **Ask before anything that deletes data**: `docker compose down -v`,
  `docker volume rm`, removing the checkout. `docker compose down` without
  `-v` keeps the database and uploads, and needs no confirmation.
- **Do not expose port 18060 beyond the machine** without reading
  `SECURITY.md` with the user first. The default deployment answers on this
  machine only; `MIROBODY_BIND=0.0.0.0` offers it to the network, where the
  demo code is public.
- **Never commit `.env`.** `deploy.sh` creates it with mode 0600 and the
  repository ignores it; leave both as they are.
- **One stack per name.** Compose names a stack after its folder, so a second
  checkout called `mirobody` would take over the first one's containers and
  database. Run `docker compose ls` before cloning: if a `mirobody` project
  already runs from another directory, operate that one, or give the new
  checkout its own `COMPOSE_PROJECT_NAME` and ports in `.env` (`deploy.sh`
  refuses otherwise, and says so).
- **Ports come from `.env` and nowhere else.** `deploy.sh` never picks one; if
  the stack answers on another port, say which variable set it.
- **Do not skip a verification step** because the previous one printed nothing
  alarming. Each step below checks a different thing.

## Preflight

```bash
docker --version && docker compose version    # Docker 24+ with Compose v2
git --version
```

The download is about 390 MB (the app image about 230 MB, Postgres about
160 MB), and the stack uses ports `18060` (app) and `18062` (Postgres), both
bound to localhost only. If either port is taken, set `MIROBODY_HOST_PORT` or
`PG_HOST_PORT` in `.env` before step 2; `deploy.sh` checks both and names the
one to change. No Python, Node.js, GPU or Git LFS is needed on the host, and
no Git either: the release tarball
(`curl -L https://github.com/thetahealth/mirobody/archive/refs/heads/main.tar.gz | tar xz`)
is the same checkout.

## Install: two commands

```bash
git clone --depth 1 https://github.com/thetahealth/mirobody.git && cd mirobody
OPENROUTER_API_KEY=sk-or-... ./deploy.sh
```

What `deploy.sh` does, so you can explain it: writes the five secrets the
stack needs into `.env` (generated with `openssl rand`), and the model key
given in its environment too; pulls the published image
`thetahealth4mirobody/mirobody`; starts Postgres, the server and the worker
with `docker compose up -d --wait`; and prints the demo sign-in. If Docker Hub
is unreachable from the daemon it switches to a mirror on its own; if the
image cannot be pulled at all it builds one from the checkout, which takes
several minutes and needs `git lfs pull` first. It stops before starting
anything when a port is taken or another stack runs under the same name.

The key is the only thing that needs the user: run `./deploy.sh` without it
if they have not chosen one yet, and put it in `.env` later (then
`docker compose up -d`). Any ONE of these keys runs every surface (chat,
vision, text extraction):

| Provider | Variable |
| --- | --- |
| OpenRouter | `OPENROUTER_API_KEY` |
| OpenAI | `OPENAI_API_KEY` |
| Google Gemini | `GOOGLE_API_KEY` |
| Anthropic | `ANTHROPIC_API_KEY` |
| DeepSeek | `DEEPSEEK_API_KEY` |
| DashScope | `DASHSCOPE_API_KEY` |

Any OpenAI-compatible gateway works through `<PROVIDER>_BASE_URL` beside its
key (`OPENAI_API_KEY` → `OPENAI_BASE_URL`). Each `config.llm.yaml` entry names
the variable that replaces its model (`model_env`: `OPENAI_CHAT_MODEL` for
chat, `OPENAI_UTILS_MODEL` for documents), and the utilities model must be
multimodal, because report photos go to it.

**After editing `.env`, run `docker compose up -d`, not `restart`.** Compose
reads the env file when it creates a container; `restart` keeps the old
environment and the key is silently ignored.

## Verify, in this order

```bash
docker compose ps
```

Expected: `pg` healthy, `mirobody` healthy, `mirobody_worker` running,
`mirobody_init` exited with code 0 (it runs once to hand the upload volume to
the app's user).

```bash
curl -fsS http://localhost:18060/api/health
```

Expected: JSON with `"service":"mirobody"` and the version. Anything else
means the server is not up; read `docker compose logs mirobody`.

```bash
docker compose exec mirobody mirobody doctor
```

Prints one row per surface (chat, vision, text) with the provider each one
selected. **Exit status 1 with no key set is expected until the key is in**
and means "no provider anywhere"; after the key is in and `up -d` has run, it
exits 0 and every row names a provider. A row left blank with a key present
means that key's provider cannot serve that surface; the table says which.

## First use

Open `http://localhost:18060`. The sign-in page offers the demo account
(**Use it** fills the Email code tab): `you@mirobody.ai` with code `111111`.
`SEED_DEMO_DATA` is on by default, so two accounts already hold data: this
one, and `mom@mirobody.ai`, who shares her record view-only. Set
`SEED_DEMO_DATA=false` in `.env` before the first start for an empty
deployment.

- **Data page**: drop a file. `demo/upload/` in the checkout holds seven the
  seed leaves out: the 2026 lab PDF and the CSV are `you`'s, the 2026 report
  photo and spreadsheet are `mom`'s (upload those signed in as her), and
  three more are `you`'s earlier years, two in Chinese and two in mg/dL,
  printing LDL cholesterol under three names (`demo/README.md`). Each analyte
  comes out with a value, a unit and a code, linked to the page it was read
  from. A genotype export goes on the Genomics tab, not here.
- **Ask page**: a question such as "How has my cholesterol moved?" finds every
  file that carries it, whatever the lab called it, and names the file behind
  each number.
- **Journal**: a typed sentence (`headache since last night, BP 150/95`) is
  split by the model and coded from the vocabulary.

## Connect an agent over MCP

Every tool the built-in agent has is also served at `/mcp`, gated per user.
In the web app, **Settings** issues a personal MCP link. The tool list is
data-gated: an account with no lab data does not see the lab-query tool, so
an empty list is a signal to upload something, not a fault. The link goes to
a client on the same computer:

| Client | Setup |
| --- | --- |
| Claude Code | `claude mcp add --transport http mirobody <link>` |
| Codex | `codex mcp add mirobody --url <link>` |
| Cursor | `~/.cursor/mcp.json`: `{"mcpServers": {"mirobody": {"url": "<link>"}}}` |
| Gemini CLI | `gemini mcp add --transport http mirobody <link>` |
| Claude Desktop | `claude_desktop_config.json`: `{"mcpServers": {"mirobody": {"command": "npx", "args": ["-y", "mcp-remote", "<link>"]}}}` |

Do not tell the user to paste the link into Claude Desktop's "Add custom
connector", ChatGPT or claude.ai: those connect from their vendor's cloud,
which cannot reach `localhost`. They need the stack behind an HTTPS address,
which is a server deployment (`SECURITY.md` first), not this one.

The library's offline tools also run without the server, over stdio. Five
need no key (`resolve_indicator`, `normalize_unit`, `convert_unit`,
`standardize_reading`, `standardize_complaint`); `standardize_report` reads a
whole document with a model, so it needs the `[parse]` extra and one model
key, and says so when either is missing:

```bash
uvx --python 3.12 mirobody mcp
uvx --python 3.12 --from 'mirobody[parse]' mirobody mcp    # with standardize_report
```

## Operate

| Task | Command |
| --- | --- |
| Follow the server log | `docker compose logs -f mirobody` |
| Follow the extraction worker | `docker compose logs -f mirobody_worker` |
| Stop, keep all data | `docker compose down` |
| Start again | `docker compose up -d` |
| Upgrade to a new release | `git pull && ./deploy.sh` |
| Change the app port | `MIROBODY_HOST_PORT=8080` in `.env`, then `docker compose up -d` |
| Back up and restore | `docs/backup-restore.md` in the checkout |

Wearables connect from inside the app. Garmin, Oura and WHOOP are OAuth
clients of their vendor, so each needs credentials from that vendor's
developer programme; `docs/provider-setup.md` walks through it. Apple has no
API to pull from: an `export.zip` from the Health app is read on the host by
`mirobody import apple`, and a phone app pushes into a running stack through
`POST /apple/health` (`docs/apple-health.md`). The Data page does not take a
Health export.

## When something is wrong

| Symptom | Cause and fix |
| --- | --- |
| `deploy.sh` says a port is in use | Set the variable it names (`MIROBODY_HOST_PORT` or `PG_HOST_PORT`) in `.env`, run it again |
| `deploy.sh` says a Mirobody stack of that name already runs from another folder | A second checkout under the same Compose name. Operate the first one, or set `COMPOSE_PROJECT_NAME` and both ports in this checkout's `.env` |
| `uvx mirobody …` says the package provides no executables, or cannot resolve it | The default Python is older than 3.12, so uv picked an old release. Use `uvx --python 3.12 mirobody …` |
| `doctor` exits 1 after the key was added | `.env` was edited but `docker compose up -d` was not run, or the line has a typo; `grep -o '^[A-Z_]*_API_KEY=' .env` shows the name without printing the value |
| The server log says `config.localdb.yaml` is a directory | Docker Desktop mounted the overlay from a path it does not share as a file (a checkout under `/tmp` on macOS does this); the stack runs on defaults. Move the checkout under the home directory and run `./deploy.sh` again |
| `deploy.sh` says `compose.override.yaml` is from 1.5.2 | The message names the two commands; it is an upgrade from an older layout |
| Pull fails and the build says the bundle is an LFS pointer | `git lfs install && git lfs pull`, then `./deploy.sh` again |
| A report photo is not extracted | The selected model is not multimodal; `doctor` shows which model extraction chose |

## Privacy, stated once

The record lives in the stack's own Postgres volume. The only outbound calls
are to the model behind the key in `.env` and to a wearable vendor the user
linked. Name to code and unit normalization run offline inside the image.
Encryption at rest does not yet cover every field; `SECURITY.md` says what
that means before the stack reaches a network the user does not control.

