Barrel
FR GitHub

Choose a deployment

Barrel runs in three places: inside your Erlang release, as a server over HTTP, and as a local copy in a web browser. You can mix them, since they replicate with each other: a server can sync with browsers and with other servers, and every copy takes writes. Use this page to pick where to start from what your clients are and where your data must live.

The three options

Embedded

In embedded mode the barrel library runs inside your own Erlang or Elixir release, and your code calls it as functions. It fits an application that owns its data and is written in Erlang or Elixir, such as an agent runtime on an edge device. You get the full API with no network hop: record mode, the timeline, spaces. The cost is that only code in the same release can reach the data, and nothing enforces access rules between parts of that code.

Server

barrel_server runs Barrel as a service and serves it over HTTP: a REST/JSON API and an MCP endpoint that agents call as tools. It fits clients written in other languages, clients on other machines, and agents. The cost is a service to run and secure: every call crosses the network, and the server has no authentication until you configure it. You can run it from its Docker image or a release tarball without building anything; see Install.

Browser

barrel-lite keeps a copy of a database inside a web app, so reads and writes are local and keep working offline. It fits a web app that must stay usable without a network. The cost is that it needs a barrel_server to sync with, the browser may evict its copy, and vector, keyword and hybrid search run on the server, not locally.

Decide

The table maps a need to the option that answers it.

If you needUseWhy
Your app is Erlang or Elixir and owns the dataEmbedded barrelNo network hop, full API, record mode, timeline
Clients in other languages, or on other machinesbarrel_serverREST/JSON over HTTP/1.1, HTTP/2 or HTTP/3
An agent to read and write the databarrel_serverMCP endpoint at /mcp with 39 tools
A web app that works offlinebarrel-lite and barrel_serverLocal store in the browser, synced to the server
Several sites or devices that all take writesAny of them, replicatingEvery copy accepts writes and converges
Documents and sync only, no vectorsbarrel_docdbSmaller dependency, same replication
Exact substring or regex over documentsbarrel_ngram, or barrel_serverThe server exposes it as the ngram_search tool

What each mode gives you

This table lists which features each mode has, so you can check that the one you picked covers what you need.

EmbeddedServerBrowser
Documents, BQLyesyesyes, local BQL
Vector, BM25, hybrid searchyesyeson the server, through queryRemote; local cosine over synced vectors
Attachmentsyesyesyes
Replicationbarrel_rep_sync routespush and pull to a server
Branch, merge, past stateyes_timeline routesno
Spaces, sessions, handoffsbarrel_spaces/spaces, /handoffs, MCPno
Authenticationin process, nonebearer, capability tokens, signed requests, mTLSbearer or capability token
Encryption at restyesyes, through open_optsno

Things to know before you choose

These are the limits that most often change a choice.

  • Embedded means your process holds the data. The vector store is linked to the process that opens it. Open long-lived databases through barrel_dbs or with store_supervised => true. See Embed barrel in an Erlang app.
  • Capability tokens are enforced by the server. In process, any code can open any space. If agents must be kept apart, put them behind barrel_server. See Spaces and capabilities.
  • The browser copy is a cache. The browser may evict it; the server holds the durable copy.
  • Vectors do not replicate. Each copy rebuilds its own index from the documents in record mode.
  • One node is not a cluster. There is no automatic placement or failover. You choose which copies replicate with which.

Next

Written for the site Edit this page View as Markdown

Up and down to moveEnter to open