Installation

Riverbeam is a Cargo workspace. Its manifest depends on Riverbase and on the river-reed rule engine by relative path, so the three checkouts must sit side by side.

Requirements

Tool	Version	Needed for
Rust	1.78 or newer	Everything
Postgres	Any supported release; the vector extension for knowledge storage	PgBeamStore, PgVectorStore, store and knowledge tests
NATS	A running nats-server	NatsWorkerServer, NatsWorkerClient, NatsTransport, worker tests

Postgres and NATS are optional for development. In-memory stores and transports cover a single process.

Check out the workspace

mkdir riverbase-workspace && cd riverbase-workspace
git clone https://github.com/riverbase-io/riverbase
git clone https://github.com/riverbase-io/riverbeam
# river-reed must also be checked out here as ./river-reed

The layout the manifest expects:

riverbase-workspace/
├── riverbase/     # riverbase_core, riverbase_task
├── river-reed/    # GRL rule engine used by beam_security
└── riverbeam/     # this workspace

riverbase_core is built with the nats-io feature, and river_reed with grl-rule-engine. The workspace manifest already selects both.

Build and test

cd riverbeam
cargo build --workspace
cargo test --workspace

Tests that need Postgres or NATS skip themselves unless you set the connection variables:

BEAM_DATABASE_URL=postgres://USER@127.0.0.1:5432/beam \
  NATS_URL=nats://127.0.0.1:4222 \
  cargo test --workspace

Two subsystems are behind feature flags:

# Polars-backed ingest statistics
cargo test -p beam_knowledge --features polars-ingest

# pgvector store (skips when the vector extension is missing)
BEAM_DATABASE_URL=postgres://USER@127.0.0.1:5432/beam \
  cargo test -p beam_knowledge --features postgres

Add Riverbeam to your application

Put your application in the same parent directory and depend on the crates by path. Add only the crates you use:

my-agent-service/Cargo.toml

[dependencies]
beam_core = { path = "../riverbeam/crates/beam_core" }
beam_types = { path = "../riverbeam/crates/beam_types" }
beam_agents = { path = "../riverbeam/crates/beam_agents" }
beam_worker = { path = "../riverbeam/crates/beam_worker" }
beam_domain = { path = "../riverbeam/crates/beam_domain" }
beam_stream = { path = "../riverbeam/crates/beam_stream" }
riverbase_core = { path = "../riverbase/crates/riverbase_core", features = ["nats-io"] }

serde_json = "1"
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
uuid = { version = "1", features = ["v4", "serde"] }

All Riverbeam crates share one version, 0.1.0. Keep the three checkouts on matching revisions.

Database schema

PgBeamStore::connect creates simplified execution tables if they are missing, so a stock Postgres works for sessions and messages in development. For anything you keep, apply migrations/0001_beam_schema.sql before the first start: it adds foreign keys, more columns, and the pgvector, usage, audit and security tables, and it cannot upgrade tables a component already created.

psql "$BEAM_DATABASE_URL" -f riverbeam/migrations/0001_beam_schema.sql

The migration runs CREATE EXTENSION IF NOT EXISTS vector, so the database role needs permission to create extensions. See Database schema.

Next

Run an agent in one process in the quick start.