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

data:
  patients_dir: ./data
  output_dir: ./output

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

compliance:
  hipaa: false
  audit_log: ./logs/audit.jsonl

eval:
  enabled: false
  provider: mlflow
  tracking_uri: ./mlruns
  track:
    - model_inference
    - cds_card_returned
    - card_feedback

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`

`data`

Field	Type	Default	Description
`patients_dir`	path	`./data`	Directory for patient data files
`output_dir`	path	`./output`	Directory for sandbox results

`security`

Field	Type	Default	Description
`auth`	string	`none`	Authentication method — `none`, `api-key` (planned), or `smart-on-fhir` (planned)
`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

Authentication is planned, not yet active

Setting auth: api-key or auth: smart-on-fhir is accepted by the config but not yet enforced at runtime. Authentication middleware is on the roadmap. allowed_origins is functional — it controls which origins are permitted by the CORS middleware.

`compliance`

Field	Type	Default	Description
`hipaa`	bool	`false`	Mark service as HIPAA-scoped — displayed in startup banner and `healthchain status`
`audit_log`	path	`./logs/audit.jsonl`	Destination for audit log events (planned)

Audit logging is planned, not yet active

Setting hipaa: true currently marks the service as HIPAA-scoped in the CLI and startup banner. Structured audit logging (PHI access events written to audit_log) is on the roadmap but not yet implemented.

`eval`

Field	Type	Default	Description
`enabled`	bool	`false`	Enable model evaluation tracking
`provider`	string	`mlflow`	Eval backend — `mlflow`, `langfuse`, or `none`
`tracking_uri`	path	`./mlruns`	MLFlow tracking directory
`track`	list	see below	Events to capture

Default tracked events:

model_inference — input features and prediction for each request
cds_card_returned — which card was shown to the clinician
card_feedback — whether the clinician accepted, overrode, or ignored the card

The card_feedback event closes the evaluation loop — it provides implicit ground truth for model performance regardless of whether your model is an ML classifier, NLP pipeline, or LLM.

Note

MLFlow integration is on the roadmap. Setting eval.enabled: true prepares your project for when it ships.

`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