--- title: "Environment variables" description: "The canonical, exhaustive reference for every environment variable the Rayfin CLI and runtime read or write — frontend, tooling, feature flags, and file locations." url: https://rayfin.ai/docs/reference/config/environment-variables markdown_url: https://rayfin.ai/docs/reference/config/environment-variables.md section: reference product: Rayfin sdk_version: 1.34.0 cli_version: 1.33.2 last_updated: 2026-08-29T23:37:34-07:00 source: reference/config/environment-variables.mdx --- # Environment variables > The canonical, exhaustive reference for every environment variable the Rayfin CLI and runtime read or write — frontend, tooling, feature flags, and file locations. This page is the single reference for every environment variable Rayfin tooling reads or writes. Other pages in this reference link here instead of repeating the tables. ## Frontend-visible variables (`RAYFIN_PUBLIC_*`) [#frontend-visible-variables-rayfin_public_] These live in `rayfin/.env` and are the **only** variables exposed to frontend builds. [`rayfin env`](/docs/reference/cli/env) (or the auto-emit built into `rayfin up`) maps them to framework-specific names in `.env.local`. | Variable | Description | Populated by | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | | `RAYFIN_PUBLIC_API_URL` | Deployed Fabric backend URL. | `rayfin up` | | `RAYFIN_PUBLIC_PUBLISHABLE_KEY` | Public key for Rayfin SDK initialization. | `rayfin up` | | `RAYFIN_PUBLIC_ITEM_ID` | Fabric AppBackend 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 (e.g. `https://app.fabric.microsoft.com/`). | `rayfin up` | | `RAYFIN_PUBLIC_SERVICE_MODE` | `rayfin` (real backend) or `mock` (local testing). | User-set in `rayfin/.env` | | `RAYFIN_PUBLIC_FRONTEND_PORT` | Stable per-project frontend dev-server port, assigned once and reused so the dev server pins a deterministic origin the deployed backend can allow-list. | `rayfin up` | ### Framework mapping [#framework-mapping] `rayfin env --framework ` maps each `RAYFIN_PUBLIC_*` variable to a framework-specific name: | Source (`rayfin/.env`) | Vite (`.env.local`) | Next.js (`.env.local`) | Plain (`.env.local`) | | ------------------------------- | ----------------------------- | ------------------------------------ | -------------------- | | `RAYFIN_PUBLIC_API_URL` | `VITE_RAYFIN_API_URL` | `NEXT_PUBLIC_RAYFIN_API_URL` | `API_URL` | | `RAYFIN_PUBLIC_PUBLISHABLE_KEY` | `VITE_RAYFIN_PUBLISHABLE_KEY` | `NEXT_PUBLIC_RAYFIN_PUBLISHABLE_KEY` | `PUBLISHABLE_KEY` | | `RAYFIN_PUBLIC_ITEM_ID` | `VITE_FABRIC_ITEM_ID` | `NEXT_PUBLIC_FABRIC_ITEM_ID` | `ITEM_ID` | | `RAYFIN_PUBLIC_WORKSPACE_ID` | `VITE_FABRIC_WORKSPACE_ID` | `NEXT_PUBLIC_FABRIC_WORKSPACE_ID` | `WORKSPACE_ID` | | `RAYFIN_PUBLIC_TENANT_ID` | `VITE_FABRIC_TENANT_ID` | `NEXT_PUBLIC_FABRIC_TENANT_ID` | `TENANT_ID` | | `RAYFIN_PUBLIC_PORTAL_URL` | `VITE_FABRIC_PORTAL_URL` | `NEXT_PUBLIC_FABRIC_PORTAL_URL` | `PORTAL_URL` | | `RAYFIN_PUBLIC_SERVICE_MODE` | `VITE_SERVICE_MODE` | `NEXT_PUBLIC_SERVICE_MODE` | `SERVICE_MODE` | | `RAYFIN_PUBLIC_FRONTEND_PORT` | `VITE_PORT` | `PORT` | `FRONTEND_PORT` | A custom variable follows the same generic pattern: `RAYFIN_PUBLIC_FOO` becomes `VITE_RAYFIN_FOO` (Vite), `NEXT_PUBLIC_RAYFIN_FOO` (Next.js), or `FOO` (plain). `RAYFIN_PUBLIC_FRONTEND_PORT` maps to the port variable each dev server reads (`VITE_PORT` for Vite, `PORT` for Next.js); the scaffolded `vite.config.ts` pins the server to it with `strictPort`, so if the assigned port is taken the dev server fails fast instead of silently drifting to another port. To use a different port, set `RAYFIN_PUBLIC_FRONTEND_PORT` in `rayfin/.env` and re-run `rayfin env` — `rayfin up` registers whatever value is assigned in the deployed redirect allow-list. ## Tooling overrides [#tooling-overrides] Configure CLI and extension behavior. Not exposed to the frontend. Set in `rayfin/.env` or as shell environment variables. | Variable | Description | Default | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | | `RAYFIN_FABRIC_API_URL` | Fabric REST API base URL the CLI calls. For `*.fabric.microsoft.com` hosts, accepts a bare origin or a full `/v1` URL (extra path segments are stripped). For non-Fabric hosts — for example, a credential proxy — accepts an origin plus path prefix; the prefix is preserved and `/v1` is appended only if not already present. | `https://api.fabric.microsoft.com/v1` | | `RAYFIN_FABRIC_PORTAL_URL` | Fabric portal base URL 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` | When set alone (not accompanied by a persisted `rayfin login`), the two Fabric endpoint variables apply only to the current process and aren't persisted — later invocations need the same shell or `rayfin/.env` value to keep using the override. Resolution precedence per variable: shell env var > value in `rayfin/.env` > persisted `environmentConfig` in `~/.rayfin/auth.json` > built-in default. > [!WARNING] > When `RAYFIN_FABRIC_API_URL` points at a non-`*.fabric.microsoft.com` host, the CLI sends > the Fabric bearer token it acquired to that host on every REST call. Only point this at a > host you trust to handle tokens responsibly, typically a first-party credential proxy you > operate yourself — there is currently no trusted-host allowlist. Operations that return a > `202` with a `Location` header are also a known limitation in proxy mode: the CLI follows > the absolute URL in `Location`, which usually points back at the upstream Fabric host and > bypasses the proxy. ## Shell-only variables [#shell-only-variables] Read from the shell environment. Never written to files. | Variable | Description | | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `RAYFIN_TOKEN` | Pre-acquired bearer token for headless or non-interactive usage. Bypasses interactive Entra ID login. Prefer `rayfin login --service-principal` for CI; use `RAYFIN_TOKEN` when a token is already available from an external source (e.g. `az account get-access-token`). | | `RAYFIN_WORKSPACE_ID` | Fabric workspace ID for non-interactive setup. Used with `RAYFIN_TOKEN`. | | `RAYFIN_TENANT_ID` | Entra ID tenant used by `rayfin up` for portal URLs and the `ctid` query parameter. Equivalent to `-t, --tenant ` (precedence: flag > env var > signed-in tenant). | | `RAYFIN_ENCRYPTION_FALLBACK_ENABLED` | Set to `true` to allow a plaintext token cache on systems without OS credential storage. Development only. Equivalent to `--encryption-fallback-enabled`. | | `RAYFIN_FEATURE_FLAGS` | Comma-separated list of preview feature names to enable (case-insensitive) — see the table below. | | `RAYFIN_APPINSIGHTS_CONNECTION_STRING` | Overrides the telemetry endpoint used by the CLI and the VS Code extension. | | `RAYFIN_CONFIG_DIR` | Overrides the `~/.rayfin` directory where auth state and the token cache are stored. | | `RAYFIN_TELEMETRY_OPTOUT` | Set to `1` to disable CLI telemetry — see [Telemetry](/docs/reference/cli/telemetry). | ### Recognized `RAYFIN_FEATURE_FLAGS` values [#recognized-rayfin_feature_flags-values] | Flag | Effect | Also auto-enabled by | | ------------ | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | `storage` | Exposes the Storage prompt in `rayfin init`. | `services.storage.enabled: true` in `rayfin.yml` | | `functions` | Exposes `rayfin functions`, `rayfin up functions deploy`, and the Functions prompt in `rayfin init`. | `services.functions.enabled: true` in `rayfin.yml` | | `connectors` | Exposes the `rayfin connector` command group. | `services.connectors.enabled: true` or any entry under `connectors:` in `rayfin.yml` | Combine multiple flags with a comma, for example `RAYFIN_FEATURE_FLAGS=connectors,functions`. ## 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, static hosting and Functions settings. | Yes | | `rayfin/.lockfile.json` | Agent-files install record — see [Ai-files](/docs/reference/cli/ai-files). | Yes | | `.env.local` | Framework-specific frontend variables, auto-generated by `rayfin env`. | No (gitignored) | | `~/.rayfin/auth.json` | CLI authentication state (tenant, account hints, persisted environment overrides). | N/A (user home) | | `~/.rayfin/cache.bin` | Encrypted MSAL token cache (OS-backed encryption when available). | N/A (user home) | ## Resolution priority [#resolution-priority] When the same variable is defined in more than one place, the value resolves 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 defaults). See [Environment variable interpolation](/docs/reference/config/env-interpolation) for how `${VAR}` / `${VAR:-default}` inside `rayfin.yml` resolves against this same priority order. ```prompt title="Find why a frontend build has the wrong API URL" My built frontend is calling the wrong backend URL. Check rayfin/.env for RAYFIN_PUBLIC_API_URL, check whether a RAYFIN_PUBLIC_API_URL or VITE_RAYFIN_API_URL is set in my shell environment (which would take priority), and check .env.local. Tell me which value wins and why, then fix it by re-running `npx rayfin env --framework vite`. ```