Configuration reference

Beam reads configuration from environment variables and local files. Keep the local collector's loopback address separate from the remote workspace API. A browser pairing token and a workspace device credential are different credentials for different endpoints.

Environment variables

Variable	Default	Purpose
`BEAM_HOME`	`~/.beam`	Root configuration directory, including custom rules
`BEAM_DATA_DIR`	`$BEAM_HOME/data`	Collector events, scans, token, identity, and cached policy
`BEAM_PORT`	`4319`	Port used by `beam start`
`BEAM_COLLECTOR_URL`	`http://127.0.0.1:4319`	Destination for local collector requests; must be HTTP loopback
`BEAM_TOKEN`	Read from the data directory's `token` file	Override for the local collector pairing credential
`BEAM_ALLOWED_ORIGINS`	Collector defaults	Comma-separated browser origins allowed to call the collector
`BEAM_API_URL`	`https://app.agentbeam.com`	Workspace enrollment and API destination
`BEAM_DASHBOARD_URL`	`https://app.agentbeam.com`	Browser connection flow destination
`TYPESAFE_API_KEY`	Unset; falls back to a stored Jev key	Optional TypeSafe credential; does not enable Jev by itself
`BEAM_APP_TOKEN`	Unset	An app's token for `beam monitor` and `beam cve check` (servers, containers, CI); keep it in a credential store
`BEAM_LLM_PROVIDER`	Unset (the workspace's setting)	Provider for LLM review with your own key: `openai`, `anthropic`, `gemini`, `groq`, `openrouter`, `mistral`, `deepseek`, `xai`, `ollama`, `custom`, or `beam`
`BEAM_LLM_MODEL`	The provider's default	Model for your own LLM review; required for `gemini`, `xai`, `ollama` and `custom`
`BEAM_LLM_BASE_URL`	The provider's endpoint	Endpoint override; required for `custom` (any OpenAI-compatible gateway)
`BEAM_LLM_API_KEY`	The provider's usual variable	Key override; otherwise `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY` and so on
`BEAM_LLM_ALLOW_HTTP`	Unset	Set to `1` to allow sending a key over plain HTTP to a non-private host
`BEAM_MANAGED_CONFIG`	`/etc/beam/monitor.json` (macOS `/Library/Application Support/Beam/`, Windows `%ProgramData%\Beam\`)	Location of the managed `beam monitor` settings file
`BEAM_JUDGE_API_KEY`	Unset; falls back to a stored judge key	Key for the model or service used by `beam judge`; does not enable it by itself

The BEAM_LLM_* variables are read by beam monitor and by the in-app SDK. The CLI also loads them from ~/.beam/.env. A provider key that's merely present in the environment is never used until a provider is chosen. beam monitor also reads layered settings files: managed (BEAM_MANAGED_CONFIG), user (~/.beam/monitor.json) and project (beam.monitor.json), with environment variables and flags above them.

Use process-local or service-specific configuration. Never replace your operating system's HOME variable to relocate Beam data.

Change the collector port

BEAM_PORT=4400 beam start

In the terminal used to open Studio or send local requests:

export BEAM_COLLECTOR_URL=http://127.0.0.1:4400
beam studio

The listener port and client URL are separate settings. Keep them aligned. Remote HTTPS addresses are rejected as collector URLs; configure workspace destinations instead.

Understand local files

The data directory stores the collector token, bounded events and scan reports, the enrolled device identity, and cached policy.json. Custom detection rules live at $BEAM_HOME/rules.json, outside the default data subdirectory.

The collector creates private data directories and files, using directory mode 0700 and file mode 0600 on platforms supporting those permissions. Restrict backups and shared access as well; recognized-secret redaction does not remove every kind of sensitive text.

Optional Jev settings

Jev action judging stores settings and an optional credential in $BEAM_HOME/jev.json, outside BEAM_DATA_DIR. Use beam jev configure to opt in; mode defaults to observe, primitive to both, and model to jev-latest. A nonempty TYPESAFE_API_KEY overrides a stored key. Hook processes must have access to the selected key source and Beam home.

beam jev status reports presence without printing the key. A piped --key-stdin credential is stored with mode 0600; it is not encrypted. Run configuration directly as the operator. beam jev disable removes the stored key and resets settings, but does not unset environment variables or revoke the provider credential. Invalid settings skip this optional integration and report an error.

Configure services and MCP

Background service installation records the resolved data directory. Review service definitions rather than relying on shell exports after login. MCP hosts may also launch processes with a different PATH or environment from your terminal.

The MCP wrapper has a BEAM_BIN override for the CLI executable. Its current collector token lookup uses $BEAM_HOME/data/token rather than BEAM_DATA_DIR; pass BEAM_TOKEN securely when using a custom data directory with the MCP status tool.