Barrel
FR GitHub

Give each agent a space, and share it by token.

A space is a database an agent works in. You share it by handing out a capability token for read, write or admin; you take it back by revoking the token. Sessions keep an agent's messages and working state, and a handoff passes a task to another agent with its context in place.

Agents reach all of it over MCP or REST. The same operations exist in Erlang when your agents run in the same node.

Spaces, sessions, handoffsMCP endpoint

What it is

Five pieces, each a thin layer over a barrel database. Spaces open through the database lifecycle manager, so idle spaces close themselves and hundreds of short-lived ones stay cheap.

Space
A barrel database created through barrel_spaces, with a generated name (sp_ and 16 characters) and a registry document. Documents, search and timeline all work in it.
Capability token
A bsp_ token granting read, write or admin on one space, optionally with an expiry. It is shown once; only its SHA-256 hash is stored.
Session
A working context for one agent inside a space: messages in order, structured data, pinned context. Its TTL slides on every change, or it never expires.
Handoff
A task passed to another agent as a token. Whoever holds it accepts, gets a session in the same space and reads the sender’s context in place.
MCP endpoint
39 tools at /mcp on barrel_server: documents, BQL, search, branches, spaces, sessions, handoffs and contexts, with the token checked per tool.

How a token is checked

barrel_server reads the token on every request. A capability token passes only on its own space’s routes and the agent routes, with the right it was granted: read covers GETs, queries, search and the pull side of sync; write adds document writes and the push side.

  1. Agent MCP client or HTTP

    Authorization: Bearer bsp_...

  2. barrel_server checks the grant: space and right

    allowed: read, or read and write

  3. Space sp_... documents, sessions, search

How a handoff moves a task

  1. Alice session in the space

    handoff_create: a token, once

  2. Token held by Bob

    handoff_accept: first wins

  3. Bob own session, same space

    handoff_complete

  4. Done token revoked
Nothing is copied: Bob reads Alice's session and documents in the shared space.

What holds, and what tests it

Over REST and MCP. Inside your own node, read the first limit below.

A token opens one space, with one set of rights

A read token cannot write, cannot touch another space, and cannot create or delete databases or branch them. Unmapped routes refuse it.

Checked by barrel_server_auth_SUITE: t_capability_read_scope, t_capability_wrong_space, t_capability_fail_closed; barrel_caps_SUITE t_rights_ladder.

Revocation takes effect on the next request

A revoked or expired token answers 401. Dropping a space revokes every grant on it.

Checked by t_revoked_401 in barrel_server_spaces_SUITE, t_revoke and t_drop_space_revokes in barrel_caps_SUITE.

A handoff is accepted once

Accepting flips the handoff from pending to accepted with a compare-and-set; a second accept answers already_accepted. Completing revokes the token by default.

Checked by t_double_accept and t_complete_revokes in barrel_handoff_SUITE.

Sessions expire on their own

An expired session reads as not found at once; the TTL sweeper tombstones it and a janitor collects its messages. A session with ttl => infinity never expires.

Checked by barrel_session_SUITE: t_sliding_ttl, t_janitor_orphans, t_no_ttl_durable.

Tokens never sit on disk in clear

The registry stores a hash of each token. Listing grants never returns hashes.

Checked by t_hash_stored_as_hex and t_list_strips_hashes in barrel_caps_SUITE.

MCP denials come back as tool results

A tool call outside the grant returns isError: true with a reason the agent can read, not a protocol failure.

Checked by t_capability_denies in barrel_server_mcp_agent_SUITE.

Use it

Create a space and grant a read token

{ok, #{id := SpaceId, db := Db}} =
    barrel_spaces:create_space(#{label => <<"joint research">>,
                                 vectordb => none}),
{ok, _} = barrel:put_doc(Db, #{<<"id">> => <<"notes">>,
                               <<"text">> => <<"draft v1">>}),
{ok, ReadTok, _Grant} = barrel_caps:grant(SpaceId,
    #{rights => [read], subject => <<"carol">>}),
barrel_caps:verify(ReadTok, SpaceId, write).
Output of the last Erlang call: a read token asking for write, recorded on barrel_spaces 1.3.1
{error,forbidden}

Keep a session

{ok, Sid} = barrel_session:create(Space,
    #{agent => <<"alice">>, ttl => 1800}),
{ok, _} = barrel_session:add_message(Space, Sid,
    #{role => <<"user">>, content => <<"draft is half done">>}),
{ok, _} = barrel_session:set_data(Space, Sid, <<"cursor">>, 42),
{ok, _} = barrel_session:pin_context(Space, Sid,
    #{content => <<"deadline friday">>, priority => 0}),
{ok, Msgs} = barrel_session:get_messages(Space, Sid,
    #{limit => 50, order => desc}).

Hand the task to another agent

{ok, #{token := HTok}} = barrel_handoff:create(Space, #{
    task_name => <<"finish the draft">>,
    from_agent => <<"alice">>, to_agent => <<"bob">>,
    from_session => Sid,
    pending => [<<"polish conclusion">>]}),

%% bob, holding only the token
{ok, #{space := BobSpace, session := BobSid}} =
    barrel_handoff:accept(HTok, #{agent => <<"bob">>}),
{ok, _} = barrel_handoff:complete(HTok,
                                  #{result => <<"shipped">>}).
Lines printed by the recorded Erlang flow (abridged)
accepted: {<<"accepted">>,<<"bob">>}
second accept: {error,already_accepted}
bob reads alice's messages: [<<"draft is half done">>]
handoff token after complete: {error,revoked}

Turn on the MCP endpoint

It is on by default in the server build. A server token gets full access; a capability token is scoped to its space and rights.

sys.config
{barrel_server, [
    {auth, #{tokens => [<<"server-token">>]}},
    {mcp, #{enabled => true,
            allowed_origins => any,
            resources => full}}
]}

Limits

  • In your own Erlang node, tokens are checked only where code calls barrel_caps:verify/3. barrel_spaces:open_space/1 and the barrel_session calls take no token, so any code in the VM can open any space. barrel_server and /mcp enforce tokens; in process, per-space encryption is the isolation boundary.
  • In barrel_handoff, accept, complete and chain check only the read right, so a read-only handoff token can complete or chain.
  • Granting, revoking and creating handoffs from Erlang take no token: the admin right is enforced by the server routes only.
  • Encrypted spaces are reachable from the Erlang API only, not over REST or MCP.
  • A space’s vector store lives on each node and does not replicate. Grants live in the registry database, so a revocation reaches other nodes at replication speed.
  • /mcp accepts bearer tokens only, server or capability; signed requests and mTLS do not apply to it. tools/call answers arrive as server-sent events.
  • Contexts across several databases need a LIMIT (1000 at most) and do not merge BM25 or hybrid scores across contexts; live federation is planned.

The libraries behind it

Up and down to moveEnter to open