Configuration Reference

healthchain.yaml is the project configuration file generated by healthchain new. It is read automatically by healthchain serve and healthchain status.

name: my-app
version: "1.0.0"

service:
  type: cds-hooks
  port: 8000

security:
  auth: none              # none | api-key
  tls:
    enabled: false
    cert_path: ./certs/server.crt
    key_path: ./certs/server.key
  allowed_origins:
    - "*"

compliance:
  audit_log: ./logs/audit.jsonl

site:
  name: ""
  environment: development

# FHIR data sources — credentials stay in .env
# sources:
#   medplum:
#     env_prefix: MEDPLUM

# LLM provider for LangChain-based pipelines
# llm:
#   provider: anthropic
#   model: claude-opus-4-6
#   max_tokens: 512

`service`

Field	Type	Default	Description
`type`	string	`cds-hooks`	Service type — `cds-hooks` or `fhir-gateway`
`port`	int	`8000`	Port for `healthchain serve`

`security`

Field	Type	Default	Description
`auth`	string	`none`	Authentication method — `none` or `api-key`
`tls.enabled`	bool	`false`	Enable TLS — passes cert/key to uvicorn automatically
`tls.cert_path`	path	`./certs/server.crt`	Path to TLS certificate
`tls.key_path`	path	`./certs/server.key`	Path to TLS private key
`allowed_origins`	list	`["*"]`	CORS allowed origins — passed directly to FastAPI's CORS middleware

API key authentication

Setting auth: api-key enforces authentication on all routes except /health, /docs, /redoc, and /openapi.json. Set HEALTHCHAIN_API_KEY in your .env file — the service logs a warning at startup if the env var is missing. allowed_origins controls which origins are permitted by the CORS middleware.

`compliance`

Field	Type	Default	Description
`audit_log`	path	`null`	Path to write audit log entries — one JSON line per request

Audit logging

When audit_log is set, every request is appended as a JSONL entry containing timestamp, method, path, status_code, duration_ms, request_id, and user. The log directory is created automatically if missing. When api-key auth is also enabled, user records the authenticated identity.

`site`

Field	Type	Default	Description
`name`	string	`""`	Hospital or organisation name — displayed in `healthchain status`
`environment`	string	`development`	Deployment environment — `development`, `staging`, or `production`

`sources`

Declare FHIR data sources here. Credentials stay in environment variables — only source names and env prefixes are stored in config.

sources:
  medplum:
    env_prefix: MEDPLUM   # reads MEDPLUM_CLIENT_ID, MEDPLUM_BASE_URL, etc.
  epic:
    env_prefix: EPIC

Field	Type	Default	Description
`<name>`	object	—	Arbitrary source name used in `gateway.search(..., source="<name>")`
`<name>.env_prefix`	string	—	Prefix for env vars: `{PREFIX}_CLIENT_ID`, `{PREFIX}_CLIENT_SECRET`, `{PREFIX}_BASE_URL`, `{PREFIX}_TOKEN_URL`

With sources declared, use FHIRGateway.from_config() instead of gateway.add_source():

from healthchain.gateway import FHIRGateway
from healthchain.config.appconfig import AppConfig

gateway = FHIRGateway.from_config(AppConfig.load())

`llm`

LLM provider settings for LangChain-based pipelines. API key is read from the standard environment variable for each provider (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.).

llm:
  provider: anthropic
  model: claude-opus-4-6
  max_tokens: 512

Field	Type	Default	Description
`provider`	string	`anthropic`	LLM provider — `anthropic`, `openai`, or `google`
`model`	string	`claude-opus-4-6`	Model ID passed to the LangChain chat model
`max_tokens`	int	`512`	Maximum tokens for model response

Use llm.to_langchain() to instantiate the configured model:

from healthchain.config.appconfig import AppConfig

config = AppConfig.load()
llm = config.llm.to_langchain()  # returns ChatAnthropic / ChatOpenAI / ChatGoogleGenerativeAI