Quickstart

RVBBIT is technically a Postgres extension plus a few helper processes, but for v1 you should treat it like a database: one Docker Compose file brings up Postgres 18 with the extension preinstalled, the Duck/Vortex query worker, the Data Rabbit desktop UI, and a Warren agent for deploying capability sidecars.

Already run Postgres? The Docker ensemble is the simplest way in, but RVBBIT is additive onto a Postgres 18 you already have — start with just the extension and add the query worker and self-hosted models only as you need them. See Existing Postgres. If you have used TimescaleDB or similar "it's really an extension" databases, the shape is the same.

Start The Stack#

Requirements: Docker with Compose, and about 4 GB of free RAM for the base stack. One line:

curl -fsSL https://rvbbit.ai/install.sh | bash

The installer currently pins the coordinated 4.2.6 release. To pin a different published release explicitly, set RVBBIT_VERSION before running it. Re-running the installer keeps an existing Compose file intact; upgrade an existing install by pulling the updated file (after preserving any local changes) and recreating the services:

cd rvbbit
curl -fsSL https://rvbbit.ai/docker-compose.yml -o docker-compose.yml
RVBBIT_VERSION=4.2.6 docker compose pull
RVBBIT_VERSION=4.2.6 docker compose up -d

The script is short and readable - it checks for Docker, downloads docker-compose.yml into ./rvbbit/, runs docker compose up -d, and waits for Postgres to report healthy. If you prefer to do exactly that by hand:

# Optional: export provider keys first so LLM-backed operators work.
export OPENROUTER_API_KEY=sk-or-...

mkdir rvbbit && cd rvbbit
curl -fsSL https://rvbbit.ai/docker-compose.yml -o docker-compose.yml
docker compose up -d

That starts everything from published images:

Service	Image	What it is
postgres	ghcr.io/ryrobes/rvbbit-postgres	Postgres 18 + pg_rvbbit, on host port 55433. Migrations apply automatically on every up, so image upgrades are safe.
duck	(same image)	The shared Duck/Vortex query worker pool.
lens	ghcr.io/ryrobes/rvbbit-lens	The Data Rabbit desktop UI on host port 3000.
warren	ghcr.io/ryrobes/rvbbit-warren-agent	Deploys capability sidecars (local models, runtimes, MCP gateways) via the mounted Docker socket.
bootstrap	(one-shot)	Deploys and verifies the baseline capabilities on first start, then exits.
doc-extract	ghcr.io/ryrobes/rvbbit-doc-extract	Parses staged documents for the document brain.
warehouse-mcp	opt-in	The Warehouse MCP server, published-artifact hub, Artifact Lens, and optional Hermes-backed Calliope notebook. Configure OAuth or WAREHOUSE_MCP_KEY, then start with docker compose --profile warehouse up -d.
gdrive-connector	opt-in	Google Drive ingestion for the document brain; start with the gdrive profile after configuring its service-account key.

Provider API keys (OPENROUTER_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, …) are passed through from your shell environment into the containers. None are required to boot - local CPU embeddings work out of the box - but LLM-backed operators need at least one.

If you only want the database (no UI, no Warren), the single container works too:

docker run -d --name rvbbit \
    -p 55433:5432 \
    -e POSTGRES_PASSWORD=rvbbit \
    ghcr.io/ryrobes/rvbbit-postgres:latest

For NVIDIA hosts there is a GPU overlay (docker-compose.gqe.yml) that pulls the prebuilt GQE engine image (~9GB, covers every CUDA CC 8.0+ card from RTX 30-series to Blackwell) - see the GPU host preflight on that page first.

Connect#

psql postgresql://postgres:rvbbit@localhost:55433/rvbbit

And open the UI: http://localhost:3000 - it comes pre-connected to the stack's own Postgres (a seeded "rvbbit (this stack)" connection; lens ≥ 3.0.5). Add more connections to any Postgres you like - remember they resolve from the lens server, so inside the ensemble the stack's database is postgres:5432, not localhost. Against an rvbbit-enabled database the whole rvbbit surface lights up. The extension is already created; you never run CREATE EXTENSION yourself on the Docker path.

Check The Install#

Cheap diagnostics should work before you run paid or live-provider calls:

SELECT * FROM rvbbit.doctor(false);
SELECT * FROM rvbbit.provider_doctor(false);

Use live mode only when you intentionally want active provider probes:

SELECT * FROM rvbbit.provider_doctor(true);

Install Clover (Hosted Operators, No UI Needed)#

Clover is RVBBIT's managed capability: ~50 semantic operators (clover_* specialists + clover_llm_* generalist functions) whose inference runs on hosted GPUs under a flat subscription — the free tier costs $0 and issues one key at rvbbit.ai/buy/clover-free.

With RVBBIT_CLOVER_KEY set in the Postgres server's environment, install from plain psql — no browser, no desktop app:

curl -fsSL https://rvbbit.ai/clover-install.sql | psql "$DSN"

The script is generated from the same catalog the Data Rabbit UI imports, and it is idempotent — re-run it any time the catalog updates. The rvbbit-postgres Docker image also applies it automatically on first boot whenever RVBBIT_CLOVER_KEY is present. Verify with:

SELECT rvbbit.clover_means('apple pie recipe', 'dessert recipes');  -- true

Setting things up for an AI agent instead? There's a dedicated page: Setup for Agents.

Create A Semantic Operator#

Semantic operators are SQL functions backed by model calls or other capability nodes. They are stored as catalog rows (rvbbit.operators) and can be edited at runtime.

You don't have to write every operator from scratch. The core extension already seeds LLM-backed means(), about(), classify(), and extract(), and installing a capability pack adds local-specialist versions of those names plus pack-only operators - for example reranker-backed means() / about() from the BGE reranker packs and extract_pii() from the GLiNER pack. See Capability Packs for which name comes from where. The example below defines your own LLM-backed operator.

SELECT rvbbit.create_operator(
    op_name        => 'tone',
    op_arg_names   => ARRAY['text'],
    op_return_type => 'text',
    op_system      => 'Classify the tone. Reply with one lowercase word.',
    op_user        => E'MESSAGE: {{ text }}\n\nTone:',
    op_model       => 'openai/gpt-5.4-mini',
    op_max_tokens  => 8,
    op_temperature => 0.0,
    op_description => 'Classify message tone.'
);

Then call it like any other function:

SELECT id, rvbbit.tone(body) AS tone
FROM support_tickets
LIMIT 20;

Inspect the receipt trail:

SELECT receipt_id,
       operator,
       model,
       latency_ms,
       error,
       invocation_at
FROM rvbbit.receipts
ORDER BY invocation_at DESC
LIMIT 10;

SELECT rvbbit.cost_audit_summary();

Use Embeddings#

SELECT rvbbit.embed('refund request from angry customer');

For table search:

SELECT *
FROM rvbbit.knn_text(
  'support_tickets'::regclass,
  'body',
  'renewal risk after shipping failures',
  10
);

Accelerate A Table#

Acceleration is a registry: any ordinary heap table can be added to it, and RVBBIT then maintains rebuildable columnar files beside the heap. Register a table and build its first files:

SELECT rvbbit.enable_table('support_tickets'::regclass);
SELECT rvbbit.refresh_acceleration('support_tickets'::regclass);

That refresh:

• scans rows that are newer than the stored watermark,
• writes accelerator files,
• updates the acceleration metadata,
• leaves the heap intact for fallback, dump, and restore.

New tables can opt in at creation time with the USING rvbbit sugar - it produces a plain heap table that is auto-registered:

CREATE TABLE events (id bigint, payload jsonb) USING rvbbit;

refresh_acceleration also refreshes layout variants by default. To skip that work on a fast incremental refresh, pass refresh_variants => false:

SELECT rvbbit.refresh_acceleration(
  'support_tickets'::regclass,
  refresh_variants => false
);

For a from-scratch rebuild (drop and re-derive every row group), use rvbbit.rebuild_acceleration(...) instead. See Storage Acceleration for the full registry API.

Query Normally#

The point is that ordinary SQL remains ordinary SQL:

SELECT account_id, count(*)
FROM support_tickets
WHERE created_at >= now() - interval '30 days'
GROUP BY account_id
ORDER BY count(*) DESC
LIMIT 20;

The heap stays the source of truth. When acceleration is enabled, conservative, rule-based routing decides whether that query should use heap, native execution, DataFusion, Duck/Vortex, hot memory, GPU GQE on NVIDIA hosts, or another available path. Learned routing runs in shadow/observation mode only - it does not take over default routing. See Routing And Training for the details.

Check Status#

SELECT *
FROM rvbbit.acceleration_status
ORDER BY table_name;

Worker path:

SELECT *
FROM rvbbit.duck_sidecar_latest
ORDER BY last_heartbeat_at DESC;

Costs:

SELECT rvbbit.cost_audit_summary();

Next Steps#

• Use Data Rabbit - already running at localhost:3000 - to browse, query, and watch the system work.
• Use Semantic SQL to design robust model-backed operators.
• Use Semantic Functions for retrieval, classification, clustering, extraction, and evidence snippets.
• Use Retrieval and Knowledge Graph for SQL-native RAG and durable semantic memory.
• Use Receipts And Costs before exposing paid model calls to users.
• Use MCP Servers when external tool results should join with SQL.
• Use Storage Acceleration before enabling acceleration for larger reporting tables.
• Use Routing And Training before adding trained profiles or forced engine paths.