Skip to main content
Generated projects do not require environment variables by default. Use these variables when you add local encrypted credentials, API-key auth, or runtime health checks that need a key.

​
Quick Start

​
Variables

​
FENTARIS_VAULT_KEY

Explicit project-vault unlock key for servers/CI and platforms without a supported system credential store. On macOS, Fentaris normally stores a generated key in Keychain, isolated by project UUID. Fentaris never generates this variable into .env, never uses a plaintext fallback, and never regenerates a missing key over existing encrypted data. Supply it from your deployment secret manager or protected environment. Applications can also pass unlockKey or a SystemCredentialStore adapter to ProjectVault.open. Project .env loads automatically before CLI configuration imports and at core entry-point initialization. Existing process values, including empty strings, take precedence. Use applyProjectEnvironment(root) before a dynamic configuration import in custom launchers whose dependencies need the environment earlier. Environment/external reference bindings do not copy credential values into the vault or automatically switch sources.

​
FENTARIS_AUTH_KEY

Original unlock key for legacy .fentaris/credentials.enc.json and .fentaris/oauth-tokens.enc.json. Retain it with the legacy encrypted files until explicit migration, source changes, and client authentication have been verified. Legacy read/maintenance helpers resolve explicit --key, process environment, then project .env; they no longer generate keys into .env. Use FENTARIS_VAULT_KEY/Keychain for the new project vault. See migration and recovery.

​
FENTARIS_VAULT_UNLOCK_KEY

MCP-only alternative to FENTARIS_VAULT_KEY for named MCP credentials and OAuth lifecycle records. Prefer FENTARIS_VAULT_KEY so MCP, secrets, and incoming client keys use the same key. When both are set, FENTARIS_VAULT_KEY wins. MCP auth actions can explicitly select the destination key with --key; environment variables avoid putting keys in process arguments. Legacy OAuth migration always decrypts its source with the original FENTARIS_AUTH_KEY, independently of the destination key. The shared vault supports macOS Keychain or an application credential-store adapter and never writes its key to project .env.

​
FENTARIS_GUEST_API_KEY

API key used by runtime health checks for projects that still use a guest user convention.
Use this key in the x-fentaris-api-key header when connecting a client to a proxy that enables API-key identity.

​
FENTARIS_ADMIN_API_KEY

API key used by runtime health checks for projects that still use an admin user convention.
Use this key in the x-fentaris-api-key header when connecting a client to a proxy that enables API-key identity.

​
FENTARIS_API_KEY

Fallback API key used by runtime health checks when a guest or admin key is not present.

​
FENTARIS_EDGE_CONTROL_PLANE_URL

Control-plane base URL used by legacy fentaris-edge login and as the saved default after fentaris edge join device authorization and enrollment.
Prefer the explicit zero-global-install flow for first enrollment:
Use HTTPS. The enrolled gateway URL must use wss://; ws:// is accepted only for loopback development.

​
FENTARIS_EDGE_STATE_DIR

Absolute directory used for the local Edge identity, credentials, runtime status, and singleton lock. Set this before every local Edge command when testing an isolated identity or running separate Edge profiles on the same computer. On macOS and Linux, when fentaris edge join or fentaris edge service install creates a persistent service, the service preserves this value across restarts and login or boot startup.
Without this variable, Fentaris uses the native per-user location: ~/Library/Application Support/Fentaris/edge on macOS, %LOCALAPPDATA%\\Fentaris\\edge on Windows, and ${XDG_STATE_HOME:-~/.local/state}/fentaris/edge on Linux.
Keep the same value for join, run, status, and service management. Changing it selects a different local Edge identity. Reinstall the service after changing the value so its persistent environment is updated.

​
FENTARIS_EDGE_ALLOWED_EXECUTABLES

Comma-separated exact executable paths or basenames that the edge agent may start after local recipe consent. The default is empty and denies every direct executable.

​
FENTARIS_EDGE_ALLOWED_PACKAGES

Comma-separated exact package names that the edge agent may launch through npx, pnpm, yarn, or bunx. The default is empty.
Allow the concrete executable or package. Do not allow a general shell interpreter as a workaround.
Edge Control inventory, selection, and fan-out limits are application configuration, not environment variables. Configure them under McpProxyOptions.edge.control so policy review and deployment configuration remain explicit.

​
Upstream Credential Variables

Servers can also read arbitrary environment variables through credential sources.
The exact variable name depends on the project code and upstream server. Every declared credential source is required when the proxy starts. Before opening HTTP, Edge, or another first exposure transport, Fentaris resolves all declarations directly from the runtime configuration. Missing variables, unreadable local files, wrong encryption keys, or absent JSON paths are aggregated in FENTARIS_CREDENTIALS_UNAVAILABLE; run fentaris secrets setup or follow the manual action for a custom source.
Do not commit .env or .fentaris/credentials.enc.json. Generated projects ignore both by default.

​
OAuth Verification

​
FENTARIS_MCPJAM

Set to 1 to enable the repository’s mcpjam SDK conformance tests. The default test run skips them. This variable does not enable runtime OAuth authentication; configure oauthIdentityStrategy in application code.