Configuration
Riverbeam has no configuration file. A few components read environment variables; everything else is set in code when you build the pipeline.
Environment variables
| Variable | Read by | Default | Purpose |
|---|---|---|---|
BEAM_API_KEY | OpenAiCompatible::from_env, knowledge factory | none | API key for chat and embedding endpoints. NVIDIA_API_KEY is read when it is unset. |
BEAM_API_BASE_URL | OpenAiCompatible::from_env, knowledge factory | https://integrate.api.nvidia.com/v1 | OpenAI-compatible base URL |
BEAM_MODEL | OpenAiCompatible::from_env | deepseek-ai/deepseek-v4-pro-0813 | Chat model |
BEAM_DATABASE_URL | Knowledge factory | none | Postgres for pgvector. DATABASE_URL is read when it is unset. |
KNOWLEDGE_EMBEDDER | Knowledge factory | auto | openai, nvidia, mock or hash |
KNOWLEDGE_VECTOR_STORE | Knowledge factory | pgvector | pgvector or inmemory |
KNOWLEDGE_EMBEDDING_DIM | Knowledge factory | the argument you pass | Embedding width; pgvector needs 1536 |
KNOWLEDGE_EMBEDDER_MODEL | Knowledge factory | per embedder | Embedding model |
The knowledge variables are explained in Knowledge.
Fallback names
When the primary variable is unset, these older names are also read, in this order. Make sure none of them is set by accident in your environment, because they change behaviour silently:
| Primary | Fallbacks |
|---|---|
BEAM_API_KEY | GFS_BEAM_API_KEY, then NVIDIA_API_KEY |
BEAM_API_BASE_URL | GFS_BEAM_BASE_URL |
BEAM_MODEL | GFS_BEAM_MODEL |
BEAM_DATABASE_URL (knowledge factory) | DATABASE_URL, then FLRS_DATABASE_URL, then BEAM_SQL_DB_DSN |
An empty BEAM_API_KEY counts as set: the fallbacks are not read, and the factory and
OpenAiCompatible::from_env behave as if there were no key.
The library does not read these, but the examples on this site and the repository's tests use them. Use the same names in your processes:
| Variable | Default in the examples | Purpose |
|---|---|---|
NATS_URL | nats://127.0.0.1:4222 | NATS server for workers, worker clients, and stream transports |
BEAM_BIND_ADDR | 0.0.0.0:8080 | HTTP listen address of an API process |
Pass the same BEAM_DATABASE_URL to PgBeamStore::connect and the riverbase_task tracker, so all
components share one database. Setting it, together with NATS_URL, also enables the repository's
database and NATS tests.
Never commit API keys. Set them in the environment or a secret store.
Settings in code
| Setting | Where | Default |
|---|---|---|
BeamConfig | RiverBeam::new(config) | See Invoke pipeline |
| Task subject prefix | NatsWorkerServer::with_prefix, NatsWorkerClient::connect_with_prefix | beam (subjects beam.task.{task}) |
| NATS request timeout | async_nats::ConnectOptions::request_timeout, then NatsWorkerClient::new | 10 seconds (async-nats default) |
| Worker concurrency | NatsWorkerServer::with_concurrency | 16 |
| Stream subject prefix | NatsTransport::with_prefix | beam.stream |
| Delta merging | StreamConfig in BeamStream::with_config | off |
| Security policy | SecurityPolicy in SecurityManager::new | 50 steps, 128 000 tokens, recursion 10, 30 s |
| Usage plan | UsagePlan in RiverBeam::set_usage | unlimited |
| Authorization rows | BeamPolicyAuthorizer::from_csv | none; see Authorization |
| Model list | load_models_from_yaml | see Model routing |
| Domain namespace | BeamDomainBundle::with_namespace | flrs.beam |