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

irm "<install.ps1 URL shared during preview>" | iex

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

OAuth (recommended for Codex / GPT-5)OpenAI API keyAnthropic API key

Use the browser-based OAuth flow:

openmed login

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:

openmed config provider-set openai --api-key "sk-..."
openmed config provider-show

You can also use an environment variable or an environment reference in ~/.openmed/provider_secrets.json:

export OPENAI_API_KEY=sk-...

No openmed login step is required in that case.

To use Anthropic models, store an Anthropic provider key:

openmed config provider-set anthropic --api-key "sk-ant-..."
openmed config provider-show

You can also use an environment variable or an environment reference in ~/.openmed/provider_secrets.json:

export ANTHROPIC_API_KEY=sk-ant-...

Then choose a Claude model in the TUI model picker, or launch with an explicit provider/model pair:

openmed agent --provider anthropic --model claude-sonnet-4-6

Provider keys vs native medical services

OpenAI and Anthropic keys are model-provider credentials. 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-5 models route to Codex OAuth first when ~/.openmed/auth.json exists, then to the OpenAI provider key. GPT-4 models route to OpenAI.

3. Launch the agent

openmed

That starts the interactive TUI.

To launch with a specific model or inspect the model catalog:

openmed --model gpt-5.5
openmed --models

By default the app launches with model name gpt-5.5 with low 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.
• 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 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 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

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

Token expired or login fails

Re-run login:

openmed login -f

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.

Where are OAuth credentials stored?

openmed login writes only ~/.openmed/auth.json. Project-local ./auth.json is deprecated and ignored by OpenMed.