Getting Started¶
Get from zero to a running OpenMed agent in a few minutes.
1. Install¶
This places the OpenMed binary on your machine and sets up the openmed command.
OpenMed Agent is currently in preview. If you do not have a preview install link yet, request preview access.
2. Authenticate¶
Use the browser-based OAuth flow:
This writes credentials to ~/.openmed/auth.json. OpenMed uses this single OAuth file from every project and demo workspace.
If you prefer the OpenAI SDK path, store a provider key:
You can also use an environment variable or an environment reference in ~/.openmed/provider_secrets.json:
No openmed login step is required in that case.
To use Anthropic models, store an Anthropic provider key:
You can also use an environment variable or an environment reference in ~/.openmed/provider_secrets.json:
Then choose a Claude model in the TUI model picker, or launch with an explicit provider/model pair:
To use models OpenMed does not host itself — Gemini, Kimi, GLM, Llama and several hundred more — store an OpenRouter key:
Or use an environment variable:
Then launch on OpenRouter:
Choose which models appear in the /model picker:
openmed config provider-set openrouter \
--models "google/gemini-3.7-flash,qwen/qwen3.8-27b,z-ai/glm-5.2"
Without a configured model list, qwen/qwen3.8-27b is the OpenRouter default. Browse the catalog with openmed config openrouter-models. OpenMed only accepts models that support tool calling, and does not evaluate the OpenRouter catalog — see Providers for recommended models and the caveats that matter for clinical use.
Store the tp key from your Xiaomi MiMo token-plan subscription:
Or export MIMO_API_KEY="tp-..." before launching. No openmed login,
base URL, or model list is required. The default is mimo-v2.5-pro;
select any of the other built-in models in Ctrl+M / /model, or at launch:
openmed agent --provider mimo --model mimo-v2.6-pro
openmed agent --provider mimo --model mimo-v2.6-flash
Token-plan keys use the Amsterdam endpoint automatically. Pay-as-you-go
sk keys are not supported yet. See the complete
provider secrets examples.
Store one key for real-time, async and batch inference:
Or export DOUBLEWORD_API_KEY="sk-...". Start a real-time TUI session with:
The picker includes 11 generation models, starting with DeepSeek V4.1 Flash.
An optional provider models list
replaces those defaults; its first entry becomes the launch model.
Async is a separate CLI workflow, not a provider-secret setting or TUI toggle.
Follow the three-mode quickstart
for complete, copyable examples that need no repository files.
Create the example request JSON,
then run openmed responses submit request.json --service-tier flex.
Submission returns an ID to poll or resume later. For independent overnight
work, prepare a batch JSONL file
and use openmed batch submit requests.jsonl instead. See
Doubleword for setup, modes and the data boundary.
Provider keys vs native medical services
OpenAI, Anthropic, OpenRouter, MiMo and Doubleword keys authenticate model inference. Native medical services are a separate OpenMed service plane.
Standard preview binaries use OpenMed's native medical services without additional local service setup.
Need a preview build? Request preview access.
When multiple providers are configured
Claude models route to Anthropic. GPT-6.1 Sol and GPT-6 models
route to Codex OAuth first when ~/.openmed/auth.json exists, then to the
OpenAI provider key. Explicit GPT-5.5 selections prefer an API key when
available. Namespaced ids such as google/gemini-3.7-flash route
to OpenRouter. Bare mimo-v2.5-pro, mimo-v2.5, mimo-v2.6-pro, and
mimo-v2.6-flash IDs use MiMo token-plan credentials. Full details on the
Providers page. For Doubleword, pass --provider doubleword
explicitly, particularly with namespaced model IDs that OpenRouter also serves.
3. Launch the agent¶
That starts the interactive TUI.
To launch with a specific model or inspect the model catalog:
By default the app launches with model name gpt-6.1-sol with medium reasoning:
- With Anthropic provider credentials present, OpenMed can use the Anthropic SDK path.
- With Codex OAuth credentials present, OpenMed can use the Codex SDK path.
- With OpenAI provider credentials present, OpenMed can use the OpenAI SDK path.
- With only MiMo credentials configured, OpenMed selects
mimo-v2.5-pro. Use--provider mimowhen choosing MiMo alongside other configured providers. - If no network SDK is configured, the native fallback remains available.
The built-in agent modes are:
clinical— the default full clinical and operational laneconsumer— restricted personal-health workflows for imports, trends, summaries, and visit prepcoordination— restricted inbox/discharge lane for reviewer-safe patient-facing draftsplan— read-only planning and repo exploration
4. Choose a first workflow¶
Clinical extraction¶
Type a natural-language request in the input box:
Extract diseases and medications from this text and save to /tmp/entities.jsonl:
The patient is a 65-year-old male with Type 2 diabetes mellitus, hypertension,
and chronic kidney disease stage 3. Currently taking metformin 1000mg BID and
lisinopril 10mg daily.
A successful run typically looks like this:
- OpenMed creates a plan
- It calls
extract_entitiesfor the relevant entity types - It saves structured output to the requested file
- It reports the result inline in the TUI
Consumer health summary¶
Launch the restricted consumer lane:
Then ask for a multi-source summary:
Import this Health Connect export into /tmp/openmed-consumer-demo and run a draft consumer_summary with timeline, trends, visit-prep questions, reconciliation notes, and optional FHIR output:
@/path/to/health_connect_export.json
This lane is designed for personal-health record imports and summaries. It does not auto-send anything or write back into external systems.
Care coordination¶
Launch the restricted coordination lane:
Then ask for a reviewer-safe draft:
Normalize this portal export into a message-thread pack and run a draft clinical_inbox_triage workflow with follow-up tasks and a constrained reply draft:
@/path/to/portal_export.json
Or use the discharge workflow:
Normalize this discharge export and run a draft discharge_handoff workflow with patient instructions, clinician summary, PCP handoff, and follow-up tasks:
@/path/to/discharge_export.json
Native medical tool services
The local runtime is only part of the system. Many medical capabilities call OpenMed's native medical service plane.
- Extraction, PII, de-identification, terminology, HCC, RAF, and education tools are native OpenMed capabilities
- Preview binaries use OpenMed-hosted native services without extra local setup
- Future customer-managed deployments can move the same service plane to private cloud, VPC, or on-prem infrastructure
- Consumer-import and care-coordination adapter flows remain local-only; there is no outbound send or external-system writeback path in those lanes
These are native OpenMed tools, not MCP servers.
5. Add remote MCP servers (optional)¶
Use MCP when you want tools that OpenMed does not already ship natively:
openmed mcp add guidelines_hub https://example.com/mcp --name "Guidelines Hub"
openmed mcp doctor guidelines_hub
Once added, remote MCP tools appear under the mcp__<server_id>__<tool> namespace and can be invoked by the agent like any other tool.
6. Know where review points appear¶
- Deterministic workflows always create an immutable draft first. Ask for finalized output and the host finalizes that exact snapshot in the same run; ask for a draft, or omit the delivery state, and the draft completes the plan. Later natural language such as “looks good, send it” works without a run ID. Questions, edits, negations, failures, and ambiguous targets fail closed
- Approval dialogs for approval-gated tools such as
edit_fileare currently wired on the OpenAI SDK path - Normal read/search/extraction tool calls are still visible in the TUI even when they do not require a modal approval step
7. Enable audit traces (optional)¶
Audit is off by default. If you need a durable private record of runs, configure a private Hugging Face dataset or local-only trace store:
export OPENMED_AUDIT_HF_TOKEN=hf_...
openmed audit enable --destination hf_dataset --dataset "<user-or-org>/openmed-traces"
openmed audit status
The default audit mode stores full private transcript and tool payloads. Use openmed audit set-phi-payload preview, fingerprint, or none if you need a smaller audit record.
What's next¶
- CLI Reference — Commands, flags, SDK/auth behavior, and workflows
- Agent TUI — Shortcuts, slash commands, sessions, and interaction model
- Skills — Built-in skills and user skill packages
- Native Medical Services — Deployment boundary for extraction, terminology, coding, and education services
- MCP Connectors — Remote MCP server setup and boundaries
- Audit Trail — Optional private run traces in HF datasets, HF buckets, or local files
- Privacy & Security — Actual runtime/data-flow boundaries
Troubleshooting¶
MiMo key or model is rejected
MiMo requires a token-plan key starting with tp and one of
mimo-v2.5-pro, mimo-v2.5, mimo-v2.6-pro, or mimo-v2.6-flash.
sk pay-as-you-go keys are not supported yet.
Run openmed config provider-show to check whether the key is set without
displaying it. See MiMo troubleshooting.
MiMo takes a long time to start streaming
Read the activity label first. Preparing request… means OpenMed has not
started the primary stream yet. Waiting for model response… means it has
dispatched the primary request and has not received a reasoning or answer
delta. The direct token-plan endpoint and OpenRouter's xiaomi/... route are
separate serving paths, so their first-token latency is not expected to
match. See MiMo startup latency.
MCP server unreachable
Run the connectivity check:
Common causes: firewall rules, VPN routing, expired auth headers, or the remote endpoint not actually speaking JSON-RPC MCP.
Where are OAuth credentials stored?
openmed login writes only ~/.openmed/auth.json. Project-local ./auth.json is deprecated and ignored by OpenMed.