Embedded, server or browser: the same database.
Barrel runs inside your Erlang release, behind its own REST and MCP server, or as a local copy in a web page. The record and the replication protocol are the same in all three, so you can start with one and add the others.
Most deployments mix them: agents on a server, edge nodes embedded, users in the browser, all syncing.
How they connect
One sync wire joins them. A browser syncs with a server; servers and embedded nodes replicate with each other in either direction.
- Browser tab barrel-lite, OPFS
/db/:db/_sync, bearer
- barrel_server REST, MCP, sync wire
barrel_rep over HTTP
- Your release barrel embedded
Decide
Read across a row to compare. Each column links to its quickstart.
| Question | Embedded | Server | Browser |
|---|---|---|---|
| Choose it when | Your agents and services are Erlang or Elixir processes in one release. | Clients in other languages, agents over MCP, or other nodes need to reach the data. | A web app must keep reading and writing while offline. |
| What runs | barrel as a library in your VM. No network protocol. | barrel_server: REST and MCP over HTTP/1.1, HTTP/2 with TLS, or HTTP/3. | barrel-lite, a TypeScript client holding a local copy. |
| You need | OTP 26 or later, a C compiler and CMake for the NIFs (RocksDB, the vector index, the trigram index). | The same, built with the server profile; port 8080 by default. | A barrel_server to sync with, with CORS on and a capability token for the browser. |
| Data lives in | RocksDB under the docdb data_dir, vectors under the store’s db_path. | The server’s data_dir. Databases open on first use and close when idle. | OPFS when the browser has it, otherwise memory. The server copy is the source of truth. |
| Search | Everything: vector, BM25, hybrid, BQL table functions, substring and regex. | Vector, BM25 and hybrid over REST and MCP; substring and regex over MCP only. | Local BQL on documents and brute-force vector search over synced vectors. Keyword and hybrid go to the server. |
| Replication | barrel_rep and barrel_rep_tasks on the document database, in the VM or over HTTP. | Serves the sync wire at /db/:db/_sync, and runs tasks to other nodes. | Push, pull and live sync with one server, leader tab only. |
| Access control | Your code. Per-database encryption is the boundary between tenants. | Bearer, capability tokens, signed requests, mTLS. Open until you set auth. | Bearer only: a capability token scoped to one space. |
| Watch out for | The default vector path is relative to the current directory; set db_path. The vector store is linked to the process that opened it. | Default databases have BM25 off; set open_opts. Search configuration errors answer 500. | Unflushed writes are lost on a crash and the browser may evict the store. Not published to npm yet. |
Optional pieces, in any of them
Not in the default build. Add them where you need them.
-
Embeddings, local or cloud
A provider in
barrel_embed: Ollama, a Python virtualenv for local models, or a cloud API key. -
Reranking
barrel_rerank: Python 3 with transformers and torch, about 2 GB, model downloaded on first use. -
FAISS index
rebar3 as faiss compilewith the FAISS C++ library on the system. Linux, macOS and BSD; no Windows build. -
S3 attachments
rebar3 as s3 compile. Tested against RustFS and Garage. Not covered by encryption at rest.
Start
Embedded
{deps, [{barrel, "~> 1.14"}]}. {ok, _} = application:ensure_all_started(barrel),
{ok, Db} = barrel:open(<<"kb">>, #{vectordb => #{
db_path => "data/kb_vec", dimensions => 768}}),
{ok, _} = barrel:put_doc(Db, #{<<"id">> => <<"kb-142">>,
<<"title">> => <<"Reset a locked account">>}). Server
From the umbrella. During development, rebar3 as server shell then application:ensure_all_started(barrel_server) does the same.
rebar3 as server,prod release -n barrel_server
cd _build/server+prod/rel/barrel_server
bin/barrel_server foreground
curl localhost:8080/health {"status":"ok"} Browser
barrel-lite is not on npm yet: build it from clients/barrel-lite in the repository.
import { Database } from "barrel-lite";
const db = await Database.open("notes", {
remote: { url: "https://edge.example:8080",
db: "sp_...", token: "bsp_..." },
multiTab: true,
});
await db.put({ id: "n1", title: "hello" });
await db.sync(); // push local writes, then pull Limits
- barrel-lite 0.1.0 is not published to npm; you build it from the repository.
- The embedded API does not expose replication: call
barrel_repon the document database. - The server has no switch to turn off its HTTP listener; to serve barrel routes from your own livery service, mount
barrel_server_api:routes/1. - HTTP/3 listeners do not check client certificates; use HTTP/1.1 or HTTP/2 with TLS for mTLS.
- In the browser, storage is a cache: sync is what makes a write durable.