# Configuration reference

> Configure local storage, collector pairing, and remote workspace destinations without mixing their roles.

Source: https://docs.agentbeam.com/agent-cli/configuration

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`](https://docs.agentbeam.com/agent-cli/app-monitoring#use-your-own-key) 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](https://docs.agentbeam.com/agent-cli/app-monitoring#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

```sh
BEAM_PORT=4400 beam start
```

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

```sh
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](https://docs.agentbeam.com/agent-cli/jev) 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.