Configuration reference
Configure local storage, collector pairing, and remote workspace destinations without mixing their roles.
On this page
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 |
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.
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.