fhir-candle 2026.708.1348

fhir-candle

When you need a small FHIR.

fhir-candle is a small in-memory FHIR server that can be used for testing and development. It is NOT intended to be used for production workloads.

The project is intended to serve as a platform for rapid development and testing for FHIR - both for features in the core specification as well as Implementation Guide development.

While there are many existing OSS FHIR servers, somewhere between most and all of them are intended to support production workloads. In my own work on Reference Implementations, I often found it challenging to add the types of features I wanted due to the conflicts that causes. To that end, here are some principles I generally use while developing this project:

• No database / persisted state
• Fast startup
• Dynamically apply changes (e.g., search parameters)
• House features that would not be appropriate in production
  • E.g., provide feedback on SMART tokens to help developers

FHIR Foundation Project Statement

• Maintainers: Gino Canessa
• Issues / Discussion: Any issues should be submitted on GitHub. Discussion can be performed here on GitHub, or on the dotnet stream on chat.fhir.org.
• License: This software is offered under the MIT License.
• Contribution Policy: See Contributing.
• Security Information: See Security.

Contributing

There are many ways to contribute:

• Submit bugs and help us verify fixes as they are checked in.
• Review the source code changes.
• Engage with users and developers on the dotnet stream on FHIR Zulip
• Contribute features or bug fixes - see Contributing for details.

To ensure a welcoming environment, we follow the HL7 Code of Conduct and expect contributors to do the same.

Security

To report a security issue, please use the GitHub Security Advisory "Report a Vulnerability" tab.

For more information, please see the Security Readme.

Documentation

Full documentation lives in the docs/ tree:

• Users — running, configuring, and calling the server: docs/user/
  • Getting started
  • FHIR tenants
  • Loading initial data
  • Strict mode (--strict)
  • Subscriptions reference implementation
  • Using OpenTelemetry
  • $validate operation
• Contributors — architecture and internals: docs/technical/

The sections below are a quick-start; deeper detail lives in docs/.

Get Started with .Net

Install .NET 8 or newer and run this command:

dotnet tool install --global fhir-candle

Note that this software is still under heavy development.

Start a FHIR server and open the browser by running:

fhir-candle -o

Get Started with Docker

Install Docker and run these commands:

docker pull ghcr.io/fhir/fhir-candle:latest
docker run -p 8080:5826 ghcr.io/fhir/fhir-candle:latest

This runs the Docker image with the default configuration, mapping port 5826 from the container to port 8080 on the host. Once running, access http://localhost:8080/ for the UI, or the default endpoints:

• http://localhost:8080/fhir/r4/ for FHIR R4
• http://localhost:8080/fhir/r4b/ for FHIR R4B
• http://localhost:8080/fhir/r5/ for FHIR R5

Get Started by cloning this repository

dotnet run --project src/fhir-candle/fhir-candle.csproj

For arguments, build, and release-output details on all platforms, see Getting started.

More configuration and features

• FHIR tenants — choose FHIR versions/endpoints with --r4 / --r4b / --r5.
• Loading initial data — seed resources with --fhir-source.
• Strict mode (--strict) — strict spec-conformant REST posture for conformance testing.
• Subscriptions reference implementation — run the FHIR Subscriptions RI stack.
• Using OpenTelemetry — export traces via --otel-otlp-endpoint.
• $validate operation — structural resource validation.

To-Do

Note: items are unsorted within their priorities

High priority

• Feature/module definitions for selective loading Build interfaces for Hosted Services, etc. Add module tag to Operation, etc. Conditional loading based on discovery within types
• Persistent 'unsubscribe' list
• Finish search evaluators (remaining modifier combinations)
• Save/restore points
• Resource display / edit in UI
• Resource editor design improvements
• Add loading packages/profiles to CapabilityStatement
• Configuration and content loading via GH repos
• SQL-on-FHIR ViewDefinition and runner support
• Additional MCP support

Mid Priority

• Complete SMART support
• Additional Transaction support
• OpenAPI generation
• Contained resources
• Subscription websocket support
• Runtime Operation definitions with static/template or JS scripted responses.
• Minimal build (project and image) focused on size reduction
  • Use Native AOT deployment
• Add 'core' operations (e.g., $meta-add).
• Add support for operaions within transaction bundles
• CQL support

The long tail

• Versioned Resource support
• Non-terminology validation
• Link to terminology server for full validation
• _filter support
• Runtime named queries
• GraphQL support

More Information

FHIR® is the registered trademark of HL7 and is used with the permission of HL7.