Configuration

OpenMed configuration spans local config files, auth files, session storage, workflow output directories, and environment variables.

Files And Directories

Path	Purpose
./auth.json	Project-local OAuth credentials created by openmed login
~/.openmed/auth.json	Global OAuth credentials created by openmed login --global
~/.openmed/sessions/	Persisted TUI session data
~/.config/openmed/config.toml	General CLI configuration
~/.config/openmed/profiles/	Custom configuration profiles
~/.config/openmed/skills/	User-installed local skills
~/.config/openmed/mcp_servers.json	MCP server configuration
~/.config/openmed/mcp_tools_cache.json	Cached MCP tool discovery results
/tmp/openmed/artifacts/	Default workflow artifact root
/tmp/openmed/cases/	Default case-run root

Runtime Settings

OpenMed loads per-project and per-user runtime settings that control permission policy, tool filtering, and result persistence. These are separate from the general CLI config and profiles.

Path	Purpose
./OPENMED.md	Project instructions injected into the system prompt (loaded from git root)
./.openmed/settings.json	Project-level runtime settings (loaded from git root)
~/.openmed/settings.json	User-level runtime settings

Settings cascade: CLI arguments > project settings > user settings > defaults.

Supported runtime settings keys:

Key	Type	Default	Purpose
permission_mode	auto / acceptall / denyall / plan	auto	Tool execution gating mode
allow_tools	list of tool name patterns	none	Tools always allowed (supports wildcards)
deny_tools	list of tool name patterns	none	Tools always blocked (supports wildcards)
ask_tools	list of tool name patterns	none	Tools that always prompt for approval
tool_result_persist_threshold_chars	integer	50000	Oversized results written to disk above this threshold

Use /config in the TUI to see the effective runtime configuration at any time.

Core Environment Variables

Variable	Purpose	Default / behavior
OPENAI_API_KEY	Use the OpenAI SDK path directly	unset
OPENMED_HOME	Override the ~/.openmed root used for global auth and sessions	~/.openmed
OPENMED_CONFIG	Override the config file path	~/.config/openmed/config.toml
OPENMED_PROFILE	Select a config profile at runtime	unset
OPENMED_WORKFLOW_ARTIFACTS_DIR	Override workflow artifact root	/tmp/openmed/artifacts
OPENMED_WORKFLOW_CASES_DIR	Override case-run root	/tmp/openmed/cases
OPENMED_SKILLS_DIR	Override the user skills directory	~/.config/openmed/skills

Native Medical Service Endpoints

OpenMed ships native medical tools, but many of them call configured remote services rather than an embedded local model binary.

Variable	Purpose	Default
OPENMED_INFERENCE_URL	Extraction and PII endpoint for tools such as extract_entities, extract_pii, deidentify_text, and batch extraction	hosted endpoint from repo defaults
OPENMED_INFERENCE_API_KEY	API key header for the inference endpoint	resolved from env, local secrets, or embedded secrets
OPENMED_INFERENCE_HF_TOKEN	Optional bearer token for the inference endpoint	falls back to HF_TOKEN
OPENMED_INFERENCE_TIMEOUT_SECONDS	Per-request timeout for extraction / PII / de-identification calls	30.0 seconds
OPENMED_MED_CODES_API_URL	PubMed and terminology endpoint for ICD-10, CPT, SNOMED, LOINC, RxNorm, MedlinePlus, HCC, RAF, and crosswalk tools	hosted endpoint from repo defaults
OPENMED_MED_CODES_API_KEY	API key header for the med-codes endpoint	resolved from env, local secrets, or embedded secrets
OPENMED_MED_CODES_HF_TOKEN	Optional bearer token for the med-codes endpoint	falls back to HF_TOKEN
OPENMED_MED_CODES_TIMEOUT_SECONDS	Shared timeout for terminology / HCC / education calls	10.0 seconds
OPENMED_SERVICE_MAX_RETRIES	Shared retry count for transient backend failures	3
OPENMED_SERVICE_RETRY_BACKOFF	Shared exponential backoff base for transient backend failures	1.0 seconds
OPENMED_SERVICE_CIRCUIT_OPEN_SECONDS	Cooldown window after repeated backend failure before reattempting the same service	120.0 seconds
OPENMED_ICD10_API_URL	Legacy alias for OPENMED_MED_CODES_API_URL	backward compatible
OPENMED_ICD10_API_KEY	Legacy alias for OPENMED_MED_CODES_API_KEY	backward compatible

These are native OpenMed tools. They are not remote MCP servers.

The repository defaults point at hosted endpoints today, but you can override them to private sandbox, on-prem, or other managed deployments.

The service split is intentional:

• OPENMED_INFERENCE_URL is the extraction and de-identification plane
• OPENMED_MED_CODES_API_URL is the terminology, HCC, RAF, RxNorm, LOINC, MedlinePlus, and PubMed plane

The point of that split is not locality for its own sake. It is to keep sensitive or high-volume clinical processing on dedicated service planes that are easier to govern, faster on long unstructured inputs, and more cost-efficient than routing every page through a frontier-model path. General agent reasoning still uses the configured model provider.

During preview, OpenMed operates these native medical services on private Hugging Face accelerated infrastructure. Later deployments can keep the same workflow surface while moving the service tier to customer-managed cloud or on-prem infrastructure.

See Native Medical Services for the deployment story and hosting patterns.

MCP Configuration

Variable	Purpose	Default
OPENMED_MCP_CONFIG_PATH	Override MCP config file path	~/.config/openmed/mcp_servers.json
OPENMED_MCP_TOOLS_CACHE_PATH	Override tool-cache path	~/.config/openmed/mcp_tools_cache.json
OPENMED_MCP_TOOLS_CACHE_TTL_SECONDS	Override discovery cache TTL	3600
OPENMED_MCP_<SERVER_ID>_ENABLED	Override a server's enabled state	unset
OPENMED_MCP_<SERVER_ID>_URL	Override a server's URL	unset
OPENMED_MCP_<SERVER_ID>_HEADERS_JSON	Override a server's auth headers	unset

Model And SDK Selection

The TUI defaults to model name gpt-5.4.

SDK selection works like this:

• If Codex OAuth credentials are present, OpenMed prefers the Codex SDK path
• If only OPENAI_API_KEY is present, OpenMed uses the OpenAI SDK path
• If neither is available, the native fallback remains available

You can choose the model at launch:

openmed agent --model gpt-5.4 --reasoning-effort medium

Or at runtime via Ctrl+M or /model.

Reasoning effort

Supported values in the current build:

• low
• medium
• high
• extra_high

OAuth

Authentication commands:

openmed login             # project-local auth -> ./auth.json
openmed login --global    # global auth -> ~/.openmed/auth.json
openmed oauth status
openmed oauth logout

Stored credentials are reused until they expire or you replace them. If login/auth status reports that the token is no longer valid, run openmed login -f to start fresh.

Session PHI Mode

OpenMed exposes a session PHI mode in the CLI/TUI:

• full
• deid
• strict

This mode is stored in session state and shown in the UI. It should be treated as workflow context, not as a universal enforcement layer by itself. Real PHI handling still depends on the tool path and configured remote services.

Profiles

openmed config profiles
openmed config profile-show dev
openmed config profile-use prod

See Profiles for built-in and custom profile details.