Skip to main content
The SDK itself only reads what you pass to initialize(). In practice most apps wire the following env vars to the SDK options:

​
Plugin variables (read directly)

The OpenClaw and Hermes plugins are configured environment-first and, unlike the SDK, read these variables themselves: BELVEDIR_API_KEY, BELVEDIR_ENDPOINT, BELVEDIR_PRIVACY_MODE, BELVEDIR_CAPTURE_SENDER, and BELVEDIR_DEBUG (stderr diagnostics when traces don’t arrive). Mind the URL shape: BELVEDIR_ENDPOINT is the full ingest URL (https://platform.belvedir.ai/api/v1/traces), not a base URL like the SDK’s BELVEDIR_BASE_URL.

​
Benchmark harness variables

If your code runs inside a Belvedir benchmark sandbox, extra variables are injected at run time: BELVEDIR_API_KEY (a per-run ingest key), BELVEDIR_BASE_URL, BELVEDIR_RUN_ID, and BELVEDIR_TASKS_FILE when the harness has a custom task set. The legacy FRACTAL_* names are also set as aliases for older drivers. The SDK does not read them automatically; pass them to initialize() and use BELVEDIR_RUN_ID as the sessionId.

​
Local development

Set the vars in .env.local (Next.js) or in your shell. The shell syntax depends on your operating system:
Add the line to ~/.zshrc or ~/.bashrc to persist it across terminal sessions.
.env files work the same on every OS (BELVEDIR_API_KEY=bv_live_..., no export), so they’re the most portable option for a team on mixed machines. If traces aren’t arriving, check your terminal for SDK warnings on startup and verify BELVEDIR_API_KEY is loaded before initialize() runs.