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.
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 grantingread,writeoradminon 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
/mcpon 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.
- Agent MCP client or HTTP
Authorization: Bearer bsp_...
- barrel_server checks the grant: space and right
allowed: read, or read and write
- Space sp_... documents, sessions, search
How a handoff moves a task
- Alice session in the space
handoff_create: a token, once
- Token held by Bob
handoff_accept: first wins
- Bob own session, same space
handoff_complete
- Done token revoked
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). curl -X POST localhost:8080/spaces \
-H 'authorization: Bearer global-token' \
-H 'content-type: application/json' -d '{"label":"team"}'
curl -X POST localhost:8080/spaces/sp_.../grants \
-H 'authorization: Bearer global-token' \
-H 'content-type: application/json' \
-d '{"rights":["read"],"subject":"agent-1"}' {"jsonrpc":"2.0","id":2,"method":"tools/call",
"params":{"name":"space_create",
"arguments":{"label":"team"}}}
{"jsonrpc":"2.0","id":3,"method":"tools/call",
"params":{"name":"space_grant","arguments":{
"space":"sp_...","rights":["read"],
"subject":"agent-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}). curl -X POST localhost:8080/spaces/sp_.../sessions \
-H 'authorization: Bearer bsp_...' \
-H 'content-type: application/json' \
-d '{"agent":"alice","ttl":1800}' {"jsonrpc":"2.0","id":4,"method":"tools/call",
"params":{"name":"session_add_message","arguments":{
"space":"sp_...","session":"ses_...",
"role":"user","content":"draft is half done"}}} 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">>}). {"jsonrpc":"2.0","id":5,"method":"tools/call",
"params":{"name":"handoff_create","arguments":{
"space":"sp_...","task_name":"finish the draft",
"from_agent":"alice","to_agent":"bob"}}}
{"jsonrpc":"2.0","id":6,"method":"tools/call",
"params":{"name":"handoff_accept",
"arguments":{"token":"bsp_...","agent":"bob"}}} 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.
{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/1and thebarrel_sessioncalls take no token, so any code in the VM can open any space. barrel_server and/mcpenforce tokens; in process, per-space encryption is the isolation boundary. - In
barrel_handoff, accept, complete and chain check only thereadright, 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.
/mcpaccepts bearer tokens only, server or capability; signed requests and mTLS do not apply to it.tools/callanswers 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.