--- title: "Environments and configuration" description: "Every environment variable file, prefix, and resolution rule Rayfin tooling reads, from frontend-visible variables to interpolation in rayfin.yml." url: https://rayfin.ai/docs/deploy/environments markdown_url: https://rayfin.ai/docs/deploy/environments.md section: deploy product: Rayfin sdk_version: 1.34.0 cli_version: 1.33.2 last_updated: 2026-08-22T22:51:33-07:00 source: deploy/environments.mdx --- # Environments and configuration > Every environment variable file, prefix, and resolution rule Rayfin tooling reads, from frontend-visible variables to interpolation in rayfin.yml. Rayfin tooling reads and writes configuration through a small set of files and a handful of variable prefixes. This page covers the concepts you need while deploying — where each kind of value lives, what it's for, and how `rayfin.yml` pulls values in from the environment. For the complete, exhaustive variable-by-variable table, see [Environment variables](/docs/reference/config/environment-variables). ## File locations [#file-locations] | Path | Purpose | Committed | | ---------------------------- | ---------------------------------------------------------------------- | --------------- | | `rayfin/.env` | All runtime and deployment values. | No (gitignored) | | `rayfin/.env.example` | Documents expected variables with placeholder values. | Yes | | `rayfin/.deployments.json` | Multi-deployment registry (item IDs, API URLs, workspace IDs). | No (gitignored) | | `rayfin/rayfin.yml` | Project configuration, service toggles, frontend framework. | Yes | | `.env.local` | Framework-specific frontend variables, auto-generated by `rayfin env`. | No (gitignored) | | `~/.rayfin/auth-state.json` | CLI authentication state (tenant, account hints). | N/A (user home) | | `~/.rayfin/token-cache.json` | Encrypted token cache (OS-backed encryption). | N/A (user home) | ## Frontend-visible variables (RAYFIN\_PUBLIC\_\*) [#frontend-visible-variables-rayfin_public_] Variables prefixed `RAYFIN_PUBLIC_` live in `rayfin/.env` and are the **only** variables exposed to frontend builds. `rayfin up` populates most of these after a deploy; `rayfin env` (run automatically by the scaffolded `predev`/`prebuild` scripts) maps them into a framework-specific `.env.local`. | Variable | Description | Populated by | | ------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------ | | `RAYFIN_PUBLIC_API_URL` | Rayfin backend URL, generated after `rayfin up` deploys to a Fabric app. | `rayfin up` | | `RAYFIN_PUBLIC_PUBLISHABLE_KEY` | Public key for Rayfin SDK initialization. | `rayfin up` | | `RAYFIN_PUBLIC_ITEM_ID` | Fabric app item ID. Used for Fabric brokered auth. | `rayfin up` | | `RAYFIN_PUBLIC_WORKSPACE_ID` | Fabric workspace ID. Used for Fabric brokered auth. | `rayfin up` | | `RAYFIN_PUBLIC_TENANT_ID` | Entra ID tenant for workspace disambiguation. | `rayfin up` | | `RAYFIN_PUBLIC_PORTAL_URL` | Fabric portal base URL. | `rayfin up` | | `RAYFIN_PUBLIC_SERVICE_MODE` | `rayfin` (real backend) or `mock` (local testing). | User-set | | `RAYFIN_PUBLIC_FRONTEND_PORT` | Stable per-project frontend dev-server port, so the deployed backend can allow-list a deterministic origin. | `rayfin up` | For Vite, `RAYFIN_PUBLIC_API_URL` becomes `VITE_RAYFIN_API_URL`, `RAYFIN_PUBLIC_PUBLISHABLE_KEY` becomes `VITE_RAYFIN_PUBLISHABLE_KEY`, and so on — a custom `RAYFIN_PUBLIC_FOO` becomes `VITE_RAYFIN_FOO` (Next.js: `NEXT_PUBLIC_RAYFIN_FOO`; plain: `FOO`). See [Environment variables](/docs/reference/config/environment-variables) for the full per-framework mapping table, and [`rayfin env`](/docs/reference/cli/env) for the command that generates `.env.local`. ## Tooling overrides [#tooling-overrides] These configure CLI behavior and are never exposed to the frontend. Set them in `rayfin/.env` or as shell variables. | Variable | Description | Default | | -------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------- | | `RAYFIN_FABRIC_API_URL` | Fabric REST API base URL the CLI calls. Useful for routing through a credential proxy. | `https://api.fabric.microsoft.com/v1` | | `RAYFIN_FABRIC_PORTAL_URL` | Fabric portal base URL used for deep links and `RAYFIN_PUBLIC_PORTAL_URL`. | `https://app.fabric.microsoft.com/` | | `RAYFIN_ENV_FILE` | Path to an alternate `.env` file. Equivalent to `--env-file`. | `rayfin/.env` | ## Service configuration flags [#service-configuration-flags] Written to `rayfin/.env` based on your `rayfin.yml` settings, and read by the Rayfin WebService: | Variable | Source (`rayfin.yml`) | Values | | ------------------ | -------------------------- | ---------------- | | `Auth__Enabled` | `services.auth.enabled` | `true` / `false` | | `Data__Enabled` | `services.data.enabled` | `true` / `false` | | `Storage__Enabled` | `services.storage.enabled` | `true` / `false` | ## Shell-only variables [#shell-only-variables] Read from the shell environment only — never written to a file. These are the ones you'll use most often around deployment and CI/CD: | Variable | Description | | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `RAYFIN_TOKEN` | Pre-acquired token for headless or non-interactive usage, bypassing interactive login. Prefer `rayfin login --service-principal` unless a token is already available from an external source. | | `RAYFIN_TENANT_ID` | Entra ID tenant used by `rayfin up`. Equivalent to `-t, --tenant ` (precedence: flag > env var > signed-in tenant). | | `RAYFIN_ENCRYPTION_FALLBACK_ENABLED` | Set to `true` to allow plaintext token cache on systems without OS credential storage. Development only. | | `RAYFIN_WORKSPACE_ID` | Fabric workspace ID for non-interactive setup, used with `RAYFIN_TOKEN`. | | `RAYFIN_FEATURE_FLAGS` | Comma-separated experimental feature names to enable. | | `RAYFIN_APPINSIGHTS_CONNECTION_STRING` | Override the telemetry endpoint for the CLI and VS Code extension. | ## Resolution priority [#resolution-priority] When the same variable is set in more than one place, Rayfin resolves it in this order (highest priority first): 1. Shell environment variable. 2. `--env-file ` CLI flag (or `RAYFIN_ENV_FILE`). 3. `rayfin/.env` file. 4. Default value (hardcoded, or from `rayfin.yml` interpolation). ## Variable interpolation in rayfin.yml [#variable-interpolation-in-rayfinyml] `rayfin.yml` supports shell-style variable interpolation, so you can keep environment-specific values (connection strings, API keys, URLs) out of the checked-in config. ```yaml title="rayfin/rayfin.yml" services: data: host: ${DB_HOST} port: ${DB_PORT:-1433} ``` * `${VAR}` — substitutes the variable. Fails with a clear error if it is unset or empty. * `${VAR:-default}` — substitutes the variable, or `default` if it is unset **or** empty (an empty string counts as unset). ```bash title="rayfin/.env" DEFINED=value EMPTY= # UNDEFINED is not set ``` ```yaml config1: ${DEFINED} # → "value" config2: ${EMPTY:-fallback} # → "fallback" (empty, uses default) config3: ${UNDEFINED:-fallback} # → "fallback" (unset, uses default) config5: ${EMPTY} # → Error! (empty without default) config6: ${UNDEFINED} # → Error! (unset without default) ``` When a value is **entirely** a variable reference, Rayfin coerces it to the matching YAML type — `port: ${DB_PORT}` with `DB_PORT=1433` in `.env` becomes the number `1433`, not the string `"1433"`. Partial interpolation (`http://localhost:${PORT}`) always produces a string. `.env` values are resolved with the same [priority](#resolution-priority) as everything else: shell environment first, then the `.env` file, then the `:-` default. See [Environment variable interpolation](/docs/reference/config/env-interpolation) for the full syntax reference, including error handling details. ```prompt title="Move a hard-coded value in rayfin.yml into .env" In my Rayfin project's rayfin/rayfin.yml, replace the hard-coded connection string under services.data with a ${DB_CONNECTION_STRING} interpolation. Add DB_CONNECTION_STRING to rayfin/.env with the current value, and add rayfin/.env to .gitignore if it isn't already there. Confirm rayfin.yml still resolves correctly by running `npx rayfin up -n` (dry run). ```