Barrel
FR GitHub

barrel_server

Barrel over HTTP: a REST API, an MCP endpoint for agents, and the replication wire that other nodes and browsers sync through.

What it solves

Agents, services and browsers that are not Erlang processes need to reach the database, with access control. barrel_server exposes databases, search, timeline, spaces and contexts over REST, serves 39 MCP tools at /mcp, and checks bearer tokens, capability tokens, signed requests or mTLS.

When to use it

  • Clients in other languages, or agents through MCP, need to read and write.
  • Nodes or barrel-lite browsers replicate over HTTP.
  • You want capability tokens enforced: the server is where they are checked.

When not to

  • Everything runs in one Erlang node: call barrel directly.

How it fits into Barrel

Used by
barrel-lite, over HTTP
Other dependencies
livery (HTTP/1.1, HTTP/2, HTTP/3) and barrel_mcp 4.5.1
On its own
Yes, as a service. It brings barrel, barrel_docdb, barrel_spaces and barrel_ngram with it. You can also mount its routes inside your own livery app.

Install

rebar.config deps
{barrel_server, "~> 1.15"}

In the umbrella: rebar3 as server compile, or rebar3 as server,prod release -n barrel_server.

Configuration

App env (barrel_server)

KeyDefaultWhat it does
http_port 8080 One cleartext HTTP/1.1 listener when listeners is not set
data_dir docdb data_dir Copied into barrel_docdb data_dir at start; vector stores go there too, as <name>.vectordb
listeners none #{http, https, http3}
tls none certfile, keyfile, cacertfile, verify
auth none (open) #{tokens => [Bin]}, or accept => [bearer, signed, mtls] with signers
max_body 1 GiB Request body limit
cors none #{origins, expose, max_age}
mcp enabled enabled, allowed_origins, resources
open_opts none Default open options for every database (BM25, embedder)

The most used keys only. For every option, see the configuration reference and the API reference.

The API by task

Databases and documents (REST)

TaskCallReturns
Create, delete a database PUT, DELETE /db/:db 201 {"ok":true,"db"}; other routes answer 404 db_not_found until it exists
Write, read, delete PUT, GET, DELETE /db/:db/doc/:id 201 {"id","ok","rev"}; 409 on a stale _rev
Bulk POST /db/:db/_bulk_docs, _bulk_get {"results":[...]}
Find POST /db/:db/find {"rows","meta"}
BQL POST, GET /db/:db/query NDJSON rows then meta; SSE for SUBSCRIBE
Changes GET /db/:db/changes JSON, SSE, or feed=continuous
Attachments PUT, GET, DELETE /db/:db/doc/:id/att/:name 201 info, raw bytes
History GET /db/:db/_history, /doc/:id/_versions versions with provenance

Search, timeline, agents (REST)

TaskCallReturns
Search POST /db/:db/search/vector, bm25, hybrid {"hits":[...]}
Branch, merge POST /db/:db/_timeline/branch, merge 201, 200 report
Spaces, grants POST /spaces, /spaces/:space/grants {"space"}, {"token","grant"}
Handoffs POST /handoffs, /handoffs/accept, /handoffs/complete handoff documents
Contexts POST /contexts/_query rows, sources, summary

MCP and embedding

TaskCallReturns
Agent tools POST /mcp (tools/list, tools/call) 39 tools: db, doc, query, search, branch, space, session, handoff, context
Mount in your app barrel_server_api:routes/0,1, router/0,1 routes, with groups and prefix

Start it

A minimal sys.config. Start with application:ensure_all_started(barrel_server).

sys.config
[
 {barrel_server, [{http_port, 8080},
                  {data_dir, "/var/lib/barrel"}]}
].

Write and query over REST

From a live run on an open server (no auth configured). Two more notes were written between the calls shown, and the run sent the query as JSON ({"query": ...}); the route also takes raw BQL as text.

Shell
curl -X PUT $B/db/demo
curl -X PUT $B/db/demo/doc/a \
  -H 'content-type: application/json' \
  -d '{"title":"hello world","kind":"note","n":1}'
curl -X PUT $B/db/demo/doc/a \
  -H 'content-type: application/json' \
  -d '{"title":"stale","_rev":"bogus"}'
curl -X POST $B/db/demo/query \
  -H 'content-type: text/plain' \
  --data-binary "SELECT id, title FROM c
    WHERE kind = 'note' ORDER BY id LIMIT 2"
Responses, from a run on barrel_server 1.13.0 (trimmed)
201 {"ok":true,"db":"demo"}

201 {"id":"a","ok":true,
     "rev":"000001a1b876972d00000000@w78160d59891ba7d7"}

409 {"error":"conflict"}

200 application/x-ndjson
{"row":{"id":"a","title":"hello world"}}
{"row":{"id":"c","title":"third"}}
{"meta":{"count":2,"bound":"limit_reached",
         "has_more":false, ...}}

Limits to know

  • Search configuration errors (bm25_not_enabled, embedder_not_configured, dimension_mismatch) answer 500, not 4xx.
  • A default database opens with a 768-dimension vector store and BM25 off; set open_opts for BM25 and hybrid.
  • There are no HTTP request metrics and no /metrics route. /health checks nothing; use /ready for readiness.
  • A bad ?since cursor on /changes silently restarts from the first change.
  • MCP accepts bearer tokens only, not signed requests or mTLS. HTTP/3 has no client-certificate check yet.
  • mTLS authenticates the CA, not the individual peer, and applies only to requests without an Authorization header.
  • There is no setting to turn off the HTTP listener.

Up and down to moveEnter to open