Environment variables
Exhaustive Rayfin 1.36.2 environment variable reference for frontend builds, CLI overrides, feature flags, telemetry, and file locations.
Rayfin reads environment variables from the shell and from rayfin/.env. Only keys that
start with RAYFIN_PUBLIC_ are projected to frontend .env.local files by
rayfin env.
Frontend-visible variables
| Variable | Description | Populated by |
|---|---|---|
RAYFIN_PUBLIC_API_URL | Rayfin backend URL selected for development or deployment. | rayfin dev, rayfin up |
RAYFIN_PUBLIC_PUBLISHABLE_KEY | Public key for Rayfin SDK initialization. | rayfin dev, rayfin up |
RAYFIN_PUBLIC_FUNCTIONS_URL | Local Functions host URL selected by rayfin dev or rayfin dev functions apply; removed when Functions are disabled so clients do not retain a stale host. | rayfin dev, rayfin dev functions apply |
RAYFIN_PUBLIC_ITEM_ID | Fabric AppBackend item ID. | rayfin up, deployment switch |
RAYFIN_PUBLIC_WORKSPACE_ID | Fabric workspace ID. | rayfin up, deployment switch |
RAYFIN_PUBLIC_TENANT_ID | Entra tenant ID. | rayfin up, deployment switch |
RAYFIN_PUBLIC_PORTAL_URL | Fabric portal base URL. | rayfin up, deployment switch |
RAYFIN_PUBLIC_SERVICE_MODE | Optional app mode such as rayfin or mock. | User-set |
RAYFIN_PUBLIC_FRONTEND_PORT | Stable per-project frontend dev-server port. Reused while available and replaced when occupied. | rayfin dev, rayfin up |
Framework mapping
Source (rayfin/.env) | Vite | Next.js | Plain |
|---|---|---|---|
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_FUNCTIONS_URL | VITE_RAYFIN_FUNCTIONS_URL | NEXT_PUBLIC_RAYFIN_FUNCTIONS_URL | FUNCTIONS_URL |
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 |
Custom RAYFIN_PUBLIC_FOO maps to VITE_RAYFIN_FOO, NEXT_PUBLIC_RAYFIN_FOO, or FOO.
Frontend port aliases
RAYFIN_FRONTEND_DEV_PORT_ALIASES stores prior occupied frontend ports that should remain
allow-listed while another process still owns them. The CLI manages this variable in
rayfin/.env; do not set it by hand.
Tooling overrides
| Variable | Default | Description |
|---|---|---|
RAYFIN_FABRIC_API_URL | https://api.fabric.microsoft.com/v1 | Fabric REST API base URL. Non-Fabric proxy URLs are allowed but receive Fabric bearer tokens. |
RAYFIN_FABRIC_PORTAL_URL | https://app.fabric.microsoft.com/ | Fabric portal base URL for deep links and public env projection. |
RAYFIN_ENV_FILE | rayfin/.env | Alternate .env path. Equivalent to --env-file where supported. |
RAYFIN_WORKSPACE_ID | — | Fabric workspace ID for non-interactive targeting by rayfin dev and rayfin up. |
RAYFIN_TENANT_ID | signed-in tenant | Tenant used by rayfin up and rayfin dev when a flag is not supplied. |
RAYFIN_TOKEN | — | Pre-acquired bearer token. Bypasses CLI login for the process. |
RAYFIN_ENCRYPTION_FALLBACK_ENABLED | false | Allows plaintext token cache storage when OS keychain encryption is unavailable. |
RAYFIN_CONFIG_DIR | ~/.rayfin | Auth, telemetry, and cache directory. |
RAYFIN_APPINSIGHTS_CONNECTION_STRING | built-in endpoint | Overrides telemetry endpoint for CLI and VS Code extension. |
RAYFIN_TELEMETRY_OPTOUT | unset | Set to 1 to disable CLI telemetry. |
RAYFIN_TELEMETRY_ENV | auto-detected | Override telemetry environment label; values are trimmed/lowercased. |
RAYFIN_FEATURE_FLAGS | unset | Comma-separated feature flags. |
When RAYFIN_FABRIC_API_URL points at a non-Fabric host, the CLI sends the Fabric bearer
token it acquired to that host on every REST call. Only use a trusted first-party proxy.
Shell-only variables
These are read from the shell and are not written to project files.
| Variable | Description |
|---|---|
RAYFIN_TOKEN | Pre-acquired bearer token for headless use. Prefer service-principal login in CI unless another trusted system already minted a token. |
RAYFIN_WORKSPACE_ID | Fabric workspace ID for non-interactive rayfin dev or rayfin up. |
RAYFIN_TENANT_ID | Entra tenant used when a tenant flag is not supplied. |
RAYFIN_ENCRYPTION_FALLBACK_ENABLED | Set to true only after keychain encryption fails. |
RAYFIN_CONFIG_DIR | Overrides the ~/.rayfin directory. |
RAYFIN_TELEMETRY_OPTOUT | Set to 1 to disable CLI telemetry. |
RAYFIN_TELEMETRY_ENV | Overrides telemetry environment labeling. |
Recognized feature flags
| Flag | Status | Effect |
|---|---|---|
storage | Experimental | Enables Storage authoring prompts and the storage skill; also auto-enabled by services.storage.enabled: true. |
functions | Removed in 1.36 | No longer needed. Functions are GA in 1.36 and available without a feature flag. |
connectors | Removed in 1.36 | No longer needed. Connector commands are visible in 1.36 without a feature flag. |
Internal rollout flags such as tools-arch-v2, up-legacy, cli-up-anonstatic, and
cli-minor-fixes are not a user-facing docs surface for managed Fabric apps.
Resolution priority
For rayfin.yml interpolation and CLI env reads, values resolve in this order:
- Shell environment variables.
- Variables from
--env-file <path>orRAYFIN_ENV_FILE. - Variables from
rayfin/.env. - Hardcoded defaults or
${VAR:-default}interpolation defaults.
For Fabric API and portal overrides, shell variables win over rayfin/.env, which wins
over persisted values in ~/.rayfin/auth.json, which wins over built-in defaults.
File locations
| Path | Purpose | Committed |
|---|---|---|
rayfin/.env | Runtime and deployment values, including RAYFIN_PUBLIC_*. | No |
rayfin/.env.example | Placeholder documentation for expected variables. | Yes |
rayfin/.deployments.json | Recorded Fabric deployments and active workspace. | No |
rayfin/rayfin.yml | Project configuration. | Yes |
rayfin/.lockfile.json | Managed agent-files baseline. | Yes |
.env.local or frontend package .env.local | Framework variables generated by rayfin env. | No |
rayfin/functions/local.settings.json | Local Functions runtime settings and local secret fallbacks. | No |
~/.rayfin/auth.json | Auth state and environment overrides. | N/A |
~/.rayfin/cache.bin | MSAL token cache. | N/A |
~/.rayfin/dev-device-id | Anonymous telemetry installation ID. | N/A |
Find the value that my frontend will use for the Rayfin API URL. Check shell variables,
rayfin/.env, and .env.local; explain which value wins according to Rayfin resolution
priority; then run `npx rayfin env --framework vite` to regenerate .env.local if needed.rayfin.yml reference
Complete Rayfin 1.36.2 rayfin.yml schema for services, static hosting, Functions, storage, connectors, and secret declarations.
Environment variable interpolation
Use ${VAR} and ${VAR:-default} in rayfin.yml with Rayfin's .env resolution, type coercion, and missing-variable errors.