Your first SMART launch

This walkthrough uses fictional local records. You do not need a vendor account, real EHR credentials, or a patient-provider account. Begin with the source download and prerequisites.

1. Start the local sandbox

With Docker running, open a terminal in the extracted source directory.

macOS or Linux:

bash ./install.sh

Windows PowerShell:

.\install.ps1

Choose Try SMART Flint. Keep the private installation directory identified by the wizard; start, status, and stop commands use that directory. The installer checks requested ports and starts the console/API plus the synthetic EHR and three Health Compass samples.

Open http://127.0.0.1:3010 and select Open local workspace. Use 127.0.0.1 consistently: callbacks and browser origins match exactly.

Docker sandbox component	Default address
Console and API	http://127.0.0.1:3010
Synthetic EHR	http://127.0.0.1:4010
Health Compass patient app	http://127.0.0.1:4100
CDS Hooks handler	http://127.0.0.1:4101
Backend assessment sample	http://127.0.0.1:4102

If ports are occupied, choose different ports in the wizard. Resume the saved installation with its existing port configuration; changing origins can invalidate registered callbacks and seeded connections.

2. Inspect the configured integration

The workspace opens on Applications. Open one of the synthetic applications and inspect its required scopes, callback URL, permitted access modes, and installations. Follow the linked organization and FHIR connection, then the EHR platform and vendor registration/client profile.

An installation binds those reusable records and its access policy. The worksheet explains the SMART Flint launch URL, EHR OAuth callback, and remaining registration tasks. Your own real vendor registration will use the worksheet from its own installation.

3. Complete a launch in Developer lab

Open Developer lab and launch the reference application through a synthetic installation. Select a fictional patient where the flow offers that choice. After authorization, inspect the activation’s normalized context and perform a FHIR read.

Try a gateway connection first. Repeat with direct access when the installation permits it. The application still receives standard FHIR resources; the change is the request route and which credential authorizes each request. Use the lab’s explicit credential-ownership transfer demonstration only after reviewing gateway, direct, and handoff.

For an EHR-initiated reference flow in the default local setup, the synthetic EHR exposes:

http://127.0.0.1:4010/epic/northstar/ehr-launch

Start a fresh launch each time. Authorization codes, activation codes, state, and launch handles are short-lived transaction material.

4. Open the Health Compass app

Open Sample library, then the patient app at http://127.0.0.1:4100. Choose a configured installation and gateway or direct route. The application establishes its own PKCE transaction, completes the launch, reads Patient and Observation resources, and presents an explained educational assessment.

Use the four fictional patient scenarios to observe current measurements, healthy-range available records, old or missing records, and very high recent blood pressure. Missing records do not count as healthy results. The composite score is unvalidated educational application logic, not a clinical risk model or diagnosis.

The other samples show a signed synchronous patient-view CDS exchange and a headless backend FHIR service. Follow the sample guide for code pointers and the source-development commands.

5. Review launch activity

Open Activations and the workspace’s launch activity. Check which application, organization, connection, and installation participated. Failed launches can appear in activity before an activation exists. Use the recorded stage and sanitized error code to distinguish an initial rejection, an EHR authorization denial, a token-exchange failure, or a later FHIR-read problem.

Never paste tokens, clinical payloads, launch URLs with query parameters, or private configuration into an issue. Keep the request ID, software version, pathway, and sanitized error code.

Prefer a source development environment?

Use Node.js 24.22.1 or a newer supported security-patched release and npm. The repository records its baseline in .nvmrc.

git clone https://github.com/davidvaccaro/smart-flint.git
cd smart-flint
npm install
npm run dev

No .env or database server is needed for the default synthetic demo. Do not use an existing production .env for this workflow. The SQLite database and generated development key live in ignored .data/; retain the key with any backup.

The source stack starts six processes: console 3010, API 3001, synthetic EHR 4010, patient app 4100, CDS handler 4101, and backend sample 4102. npm run dev:core starts only the first three. The source-development API contract is http://127.0.0.1:3001/api/openapi.json.

Stop and return later

For the Docker sandbox, use the saved installation directory shown by the wizard:

bash ./install.sh --action status --directory /path/to/saved-installation --non-interactive --no-open
bash ./install.sh --action stop --directory /path/to/saved-installation --non-interactive --no-open
bash ./install.sh --action start --directory /path/to/saved-installation --non-interactive --no-open

Windows users run .\install.ps1 with the corresponding supported options shown by .\install.ps1 --help. Stopping preserves database volumes. For source development, interrupt the development command in its terminal; keep .data/ to preserve the local workspace.

Next, configure an application and follow the integration guide.

Source references: README, installer guide, and sample library.