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

# Governance context is optional and purely declarative
# governance:
#   standards:
#     - dcb0129
#     - dcb0160
#   clinical_safety_officer: ""
#   data_access_agreement: ""
#   dpia_required: false
#   notes: ""

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-8
#   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.

`governance`

Optional deployment governance metadata. This section records context only: HealthChain does not validate compliance claims, enforce policy, or expose these values through /health or other HTTP endpoints.

governance:
  standards:
    - dcb0129
    - dcb0160
    - organisation-policy-v1
  clinical_safety_officer: Dr Jane Smith
  data_access_agreement: ./governance/daa.pdf
  dpia_required: true
  notes: Reviewed by the deployment board.

Field	Type	Default	Description
`standards`	list of strings	`[]`	Applicable governance or compliance identifiers. Values are deliberately open and are not validated against a fixed set.
`clinical_safety_officer`	string	`""`	Name or reference for the deployment's clinical safety officer
`data_access_agreement`	path or URL	`""`	Location of the signed data access agreement
`dpia_required`	bool	`false`	Whether a data protection impact assessment is required
`notes`	string	`""`	Free-form deployment governance notes

When configured, healthchain serve shows the standards and clinical safety officer in its startup banner. healthchain status also reports whether a data access agreement is configured, whether a DPIA is required, and whether notes are present; it does not print the agreement path, URL, or the note text.

`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-8
  max_tokens: 512

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

llm is validated config, not a model factory — instantiate the model with your framework of choice, e.g. LangChain's init_chat_model:

from langchain.chat_models import init_chat_model

from healthchain.config.appconfig import AppConfig

config = AppConfig.load()
llm = init_chat_model(
    f"{config.llm.provider}:{config.llm.model}",
    max_tokens=config.llm.max_tokens,
)