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
- Builds on
barrel,barrel_docdb,barrel_spaces,barrel_ngram- 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
{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)
| Key | Default | What 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)
| Task | Call | Returns |
|---|---|---|
| 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)
| Task | Call | Returns |
|---|---|---|
| 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
| Task | Call | Returns |
|---|---|---|
| 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).
[
{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.
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" 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_optsfor BM25 and hybrid. - There are no HTTP request metrics and no
/metricsroute./healthchecks nothing; use/readyfor readiness. - A bad
?sincecursor on/changessilently 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
Authorizationheader. - There is no setting to turn off the HTTP listener.