Skip to content

Getting Started

Get from zero to a running OpenMed agent in a few minutes.

1. Install

curl -fsSL "<install.sh URL shared during preview>" | bash

This places the OpenMed binary on your machine and sets up the openmed command.

2. Authenticate

Use the browser-based OAuth flow:

openmed login

By default this writes credentials to ./auth.json in the current working directory.

If you want a global auth file instead, use:

openmed login --global

That stores credentials at ~/.openmed/auth.json.

If you prefer the OpenAI SDK path, export an API key directly:

export OPENAI_API_KEY=sk-...

No openmed login step is required in that case.

3. Launch the agent

openmed

That starts the interactive TUI.

By default the app launches with model name gpt-5.4:

  • With Codex OAuth credentials present, OpenMed prefers the Codex SDK path.
  • With only OPENAI_API_KEY present, OpenMed uses the OpenAI SDK path.
  • If no network SDK is configured, the native fallback remains available.

The built-in agent modes are:

  • clinical — the default full clinical and operational lane
  • consumer — restricted personal-health workflows for imports, trends, summaries, and visit prep
  • coordination — restricted inbox/discharge lane for reviewer-safe patient-facing drafts
  • plan — 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:

  1. OpenMed creates a plan
  2. It calls extract_entities for the relevant entity types
  3. It saves structured output to the requested file
  4. It reports the result inline in the TUI

Consumer health summary

Launch the restricted consumer lane:

openmed agent --agent consumer --skill analyzing-health-data

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:

openmed agent --agent coordination --skill care-coordination

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 configured remote services.

  • Extraction and PII tools use OPENMED_INFERENCE_URL
  • PubMed, ICD-10, CPT, SNOMED, LOINC, RxNorm, MedlinePlus, HCC, and crosswalk tools use OPENMED_MED_CODES_API_URL
  • The repository defaults point at hosted endpoints, but you can override them to private sandbox, on-prem, or other managed deployments
  • 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 use a draft/finalize pattern, where final writes require a valid approval_token
  • Approval dialogs for approval-gated tools such as edit_file are 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

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
  • Privacy & Security — Actual runtime/data-flow boundaries

Troubleshooting

Token expired or login fails

Re-run login:

openmed login -f

Use --global as well if you want to replace the global auth file.

MCP server unreachable

Run the connectivity check:

openmed mcp doctor --all

Common causes: firewall rules, VPN routing, expired auth headers, or the remote endpoint not actually speaking JSON-RPC MCP.

I expected ~/.openmed/auth.json but only see ./auth.json

That is the default behavior for openmed login.

If you want the global auth location instead:

openmed login --global