Environment variables

This page lists every environment variable read by the Meridian runtime processes, the process(es) that read each one, its role, and its default. It mirrors the code; where a variable's behaviour matters, the source file is cited.

The processes referred to below are:

For the deployment topology these processes form, see Topology.

.env loading

Both proxy and endpoint import apps/api/src/env.ts first. It reads a .env file at the repository root (path resolved relative to the module) if one exists, and copies each KEY=value line into process.env only when the key is not already set — an explicit export FOO=bar in the shell always wins (apps/api/src/env.ts). Lines starting with # and malformed keys are ignored; surrounding single or double quotes on the value are stripped. There is no dotenv dependency.

The ehr-lab app loads the same repository-root .env through its own loader (apps/ehr-lab — src/infrastructure/env.ts).

Consequences:

• In a checkout, copy .env.example to .env at the repo root and restart the process after any change.
• In a container/Kubernetes deployment, inject variables through the service environment (compose env_file/environment, or a Secret) rather than copying a .env. Instance manifests are version-controlled and must never contain secrets — see Security posture.

Instance and plugin resolution

Read by both proxy and endpoint at boot.

The manifest's own registry: key takes precedence over MERIDIAN_REGISTRY; a plugin listed with a local path bypasses the registry entirely (apps/api/src/registry.ts). A declared plugin that cannot be resolved fails the boot. See Set up a plugin registry, Declare and install plugins, and the Instance manifest reference.

Restate wiring

The endpoint (re)registers its deployment on every start, idempotently (force: true) and with retry (up to ~3 min), so a manual registration step is not needed and the endpoint may start before the Restate server (apps/api/src/restate/register.ts). The registered services are generic and fixed (meridianWorkflow, record, meridianScheduler), so creating or editing a workflow never requires re-registration. See Restate integration and Why durable execution.

Run index (run store)

Read by the proxy.

The default path is relative to the process cwd, so set it explicitly (absolute path / mounted volume) in a deployment. The index only lists the runs the proxy started; the durable source of truth is Restate, so losing the index erases no runs (apps/api/src/server/run-store.ts). The SQLite driver (better-sqlite3) and the Postgres driver (pg) are imported lazily, so only the selected one is loaded. See Run store, Use a Postgres run index, and Back up and restore.

Ports and inter-process URLs

The endpoint's PORT also feeds the default RESTATE_ENDPOINT_URL (apps/api/src/restate/server.ts, register.ts). See Configure ports and adapters.

Logging

Read by both proxy and endpoint via apps/api/src/observability/logger.ts (pino).

Structured logs never contain patient payloads; a redaction list additionally censors common secret fields (*.authorization, *.apiKey, *.token, …).

Observability (OpenTelemetry)

Read by both proxy and endpoint via apps/api/src/observability/otel.ts. All OTel export is opt-in: with no OTLP endpoint set, the SDK is not started and the metric instruments are zero-cost no-ops.

The OTel service.version resource attribute is taken from npm_package_version (set by the package manager), defaulting to 0.0.0. When JSON logging is active and an OTLP endpoint is configured, logs are also shipped over OTLP. See Enable observability and Observability signals.

LLM providers

The shared low-level client (libs/llm-client/src/index.ts, @meridian/llm-client) resolves a provider's base URL and API key from the environment. It backs both the editor's workflow-generation assistant (llmComplete) and the agent runner (plugin @posos/llm). A provider is considered configured only when its API key is present; the assistant throws if called for an unconfigured provider, and an agent falls back to a mock runner when no key is set.

Workflow assistant

Read by the proxy for the editor's AI assistant endpoint (apps/api/src/server/api.ts).

See Author an agent and Use the AI assistant.

Bundled-adapter fallbacks

These are read by adapters shipped with the bundled plugins only when the corresponding value is absent from the instance manifest's adapter config; config.baseUrl (etc.) in the manifest takes precedence. They apply to whichever process resolves the port (typically the endpoint for execution ports, the proxy for terminology). See Bundled plugins.

See Connect a FHIR warehouse and Configure terminology.

Posos plugin (@posos/posos)

Read by the external Posos plugin client (external-plugins/posos/lib/client.ts) in whichever process loads it.

ehr-lab (mini-EHR)

Read server-side by the ehr-lab app (apps/ehr-lab/.env.example); none are exposed to the browser. In development the localhost defaults apply; on a remote host they become required and must be injected through the service environment.

The ehr-lab app does not talk to the proxy directly: clinical validations pass through the FHIR warehouse (a Task), and the two apps share only Blaze (FHIR_BASE_URL). See Connect a FHIR warehouse, Scan&Go / FHIR mapping (apps/ehr-lab/docs/resources/reference/fhir-mapping.md), and Set the instance locale.

Related references

• Instance manifest — non-secret, version-controlled configuration.
• Topology — how proxy, endpoint, Restate, and datastores fit together.
• Run store — the persistent run index selected by RUN_DB_URL.
• Observability signals — what the OTel exporters emit.
• Security posture — secrets vs. version-controlled config.