Configuration Matrix

Vesanor has a few different surfaces, and they do not all use the same configuration names.

This page is the fast way to answer: which setting goes where?

Recommended path

For most users, the recommended path is:

replay(client, { apiKey })
Governance Studio
zero-config governance

If you are on that path, the main settings you care about are:

apiKey or VESANOR_API_KEY
runtimeUrl
environment

Matrix

Surface	Primary purpose	Main options	Env vars	Notes
`replay()` zero-config	Studio-backed governance	`apiKey`, `runtimeUrl`, `environment`, `agent`	`VESANOR_API_KEY`, `VESANOR_ENVIRONMENT`, `NODE_ENV`	Recommended public path
`replay()` local contracts	Local enforcement from YAML	`contractsDir`, `sessionYamlPath`, `tools`, `gate`, `mode`, `compatEnforcement`	`VESANOR_API_KEY` optional	Local enforcement path, not the primary Studio authority path
`observe()`	Legacy hosted capture ingestion	`apiKey`, `endpoint`, `captureLevel`, `agent`	`VESANOR_API_KEY`, `VESANOR_DISABLE`	Uses `endpoint` option, not `runtimeUrl`
CLI hosted run push	Push run results to hosted API	none on command; push happens when API key exists	`VESANOR_API_KEY`, `VESANOR_API_URL`	Used by CLI runs and sync/doctor hosted calls
CLI live-provider execution	Run against OpenAI/Anthropic	`--provider`, `--model`	`VESANOR_PROVIDER_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`	Separate from hosted API auth
`vesanor sync`	Pull hosted contracts to local	`--agent`, `--tool`, `--output`, `--force`	`VESANOR_API_KEY`, `VESANOR_API_URL`	Direction is hosted -> local only

Zero-config governance

`apiKey`

Used to attach replay() to hosted governance.

option: apiKey
env fallback: VESANOR_API_KEY

`runtimeUrl`

Overrides the hosted runtime base URL for replay().

option: runtimeUrl
no automatic env fallback inside replay()

`environment`

Controls zero-config runtime behavior after approval.

option: environment
env fallback: VESANOR_ENVIRONMENT
final fallback: NODE_ENV

Behavior summary:

development: monitor-style behavior
staging: advisory compatibility behavior
production: protective fail-closed behavior

`observe()`

observe() is a different surface from replay().

Important distinction:

observe() uses endpoint
replay() uses runtimeUrl

observe() does not automatically read VESANOR_API_URL.

For a custom ingest URL, pass:

observe(client, {
  apiKey: process.env.VESANOR_API_KEY,
  endpoint: "https://your-host.example.com",
});

CLI hosted API settings

The CLI uses:

VESANOR_API_KEY for hosted API authentication
VESANOR_API_URL to override the hosted API base URL

That applies to hosted operations such as:

pushing run results
vesanor sync
hosted portions of vesanor doctor

Provider credentials

Provider credentials are separate from hosted Vesanor credentials.

Common cases:

VESANOR_PROVIDER_KEY
OPENAI_API_KEY
ANTHROPIC_API_KEY

Use those when the CLI or your app is calling the model provider directly.

Sync direction

vesanor sync is hosted -> local.

It pulls hosted contract state and materializes local packs. It does not push your local promoted YAML packs back into Studio authority.

If you need the local-pack path, see the archived docs under docs/legacy/advanced-local/ in the repo.

Recommended path​

Matrix​

Zero-config governance​

apiKey​

runtimeUrl​

environment​

observe()​

CLI hosted API settings​

Provider credentials​

Sync direction​

Related docs​