barrel_spaces
Give each agent, team or task its own database, and share it by handing out a token. Sessions hold an agent's working memory for a while; a handoff passes a task, and the rights to finish it, to another agent.
What it solves
Several agents working on shared data need separate databases, a way to give one agent read access and another write access, short-lived working memory, and a clean way to pass unfinished work along. barrel_spaces adds those pieces on top of barrel databases.
When to use it
- Several agents work on the same data and each should only read or write what it was given.
- An agent needs a conversation log, scratch data and pinned notes that expire on their own.
- One agent starts a task and another finishes it, with what was done and what is left.
When not to
- You only need one database for one application: use barrel directly. Spaces add the sharing and session layer on top of it.
- You need isolation between Erlang processes on the same node: tokens do not give you that (see limits); use per-space encryption.
How it fits into Barrel
- Builds on
barrel,barrel_docdb,barrel_crypto- Used by
barrel_server- Other dependencies
- none beyond the Barrel libraries
- On its own
- No. A space is a barrel database, so barrel and barrel_docdb come with it.
How a handoff moves through a space
Alice works in a space, hands the task to Bob, and Bob finishes it. Carol only holds a read token. This is the verified run below, step by step.
-
Create a space
A new barrel database, registered under an id.
barrel_spaces:create_space /1 -
Grant a token
Carol gets read rights on this space only.
barrel_caps:grant /2 -
Hand off
Alice passes the task, her session and what is pending.
barrel_handoff:create /2 -
Accept, then complete
Bob reads Alice's notes and messages, finishes, and the token is revoked.
barrel_handoff:accept /2
| Who | read | write | admin |
|---|---|---|---|
| Carol | ok | forbidden | forbidden* |
| Handoff token | ok* | ok | forbidden |
| Any token, other space | wrong_space | wrong_space* | wrong_space* |
Results of barrel_caps:verify/3. Cells marked with an asterisk were not called in the run; they follow from the rights ladder read < write < admin in barrel_caps.erl. The handoff token is revoked once Bob completes the task.
Install
{barrel_spaces, "~> 2.0"} Configuration
create_space/1 options
| Key | Default | What it does |
|---|---|---|
label, purpose, owner | none | Stored in the registry document |
session_ttl | 3600 s | Default TTL of sessions in this space |
ttl_sweep_interval | 60000 ms | How often expired sessions are swept |
vectordb | a vector store | none for documents only, or a store config map |
encryption | disabled | default or #{provider => Mod}; the in-process isolation boundary |
embedding | none | Record-mode policy for the space database |
App env (barrel_spaces)
| Key | Default | What it does |
|---|---|---|
registry_db | _barrel_spaces | Database holding spaces, grants and handoffs |
janitor_interval | 300000 ms | Registry cleanup interval |
embedder | none | Embedder used to reopen record-mode spaces |
The most used keys only. For every option, see the configuration reference and the API reference.
The API by task
Spaces
| Task | Call | Returns |
|---|---|---|
| Create a space | barrel_spaces:create_space/1 | {ok, #{id, db}} |
| Open, close | barrel_spaces:open_space/1,2, close_space/1 | {ok, Space}, or space_dropped, not_found, db_is_encrypted |
| Drop (revokes every grant) | barrel_spaces:drop_space/1,2 | ok |
| List, describe | barrel_spaces:list_spaces/0, space_info/1 | registry documents |
Capability tokens
| Task | Call | Returns |
|---|---|---|
| Issue a token | barrel_caps:grant/2 | {ok, Token, Grant}; the token is shown once |
| Check a right | barrel_caps:verify/3 | {ok, Grant} or invalid_token, revoked, expired, wrong_space, forbidden |
| Revoke | barrel_caps:revoke/1, revoke_all/1 | ok |
| Who holds it | barrel_caps:auth_context/1, list/1 | {ok, #{space, subject, rights, scopes}} |
Sessions
| Task | Call | Returns |
|---|---|---|
| Start a session | barrel_session:create/1,2 | {ok, Sid} |
| Keep it alive | barrel_session:touch/2 | {ok, _} |
| Log a message | barrel_session:add_message/3 | {ok, _} |
| Read messages | barrel_session:get_messages/2,3 | {ok, [Msg]}; options limit, order, since, before |
| Scratch data, pins | set_data/4, get_data/3, pin_context/3, list_pinned/2 | {ok, _} |
Handoffs
| Task | Call | Returns |
|---|---|---|
| Hand off a task | barrel_handoff:create/2 | {ok, #{handoff_id, token}} |
| Accept it | barrel_handoff:accept/2 | {ok, #{handoff, space, session}} |
| Finish it | barrel_handoff:complete/2 | {ok, Handoff}; revokes the token by default |
| Pass it on | barrel_handoff:chain/2 | a new handoff, instead of completing |
| Find handoffs | barrel_handoff:list/1, get/1 | handoff documents |
The flow, in code
Run with the barrel_spaces application started and barrel_docdb data_dir set.
%% p(L, V) -> io:format("~s: ~p~n", [L, V]).
{ok, #{id := SpaceId} = Space} =
barrel_spaces:create_space(#{
label => <<"joint research">>,
owner => <<"alice">>, vectordb => none}),
{ok, _} = barrel:put_doc(maps:get(db, Space),
#{<<"id">> => <<"notes">>, <<"text">> => <<"draft v1">>}),
{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, ReadTok, _Grant} = barrel_caps:grant(SpaceId,
#{rights => [read], subject => <<"carol">>}),
p("carol verify write",
barrel_caps:verify(ReadTok, SpaceId, write)),
p("carol on another scope",
barrel_caps:verify(ReadTok, <<"sp_other">>, read)),
p("tampered token",
barrel_caps:verify(<<ReadTok/binary, "x">>,
SpaceId, read)),
{ok, #{token := HTok}} = barrel_handoff:create(Space, #{
task_name => <<"finish the draft">>,
from_agent => <<"alice">>, to_agent => <<"bob">>,
from_session => Sid,
pending => [<<"polish conclusion">>]}),
p("handoff token verify write",
element(1, barrel_caps:verify(HTok, SpaceId, write))),
p("handoff token verify admin",
barrel_caps:verify(HTok, SpaceId, admin)),
{ok, #{handoff := H, space := BobSpace}} =
barrel_handoff:accept(HTok, #{agent => <<"bob">>}),
p("accepted", {maps:get(<<"status">>, H),
maps:get(<<"accepted_by">>, H)}),
p("second accept",
barrel_handoff:accept(HTok, #{agent => <<"mallory">>})),
{ok, Notes} = barrel:get_doc(maps:get(db, BobSpace),
<<"notes">>),
p("bob reads notes", maps:get(<<"text">>, Notes)),
{ok, Msgs} = barrel_session:get_messages(BobSpace, Sid),
p("bob reads alice's messages",
[maps:get(<<"content">>, M) || M <- Msgs]),
{ok, Done} = barrel_handoff:complete(HTok,
#{result => <<"shipped">>}),
p("completed", maps:get(<<"status">>, Done)),
p("handoff token after complete",
barrel_caps:verify(HTok, SpaceId, read)),
ok = barrel_caps:revoke(ReadTok),
p("carol after revoke",
barrel_caps:verify(ReadTok, SpaceId, read)). carol verify write: {error,forbidden}
carol on another scope: {error,wrong_space}
tampered token: {error,invalid_token}
handoff token verify write: ok
handoff token verify admin: {error,forbidden}
accepted: {<<"accepted">>,<<"bob">>}
second accept: {error,already_accepted}
bob reads notes: <<"draft v1">>
bob reads alice's messages: [<<"draft is half done">>]
completed: <<"completed">>
handoff token after complete: {error,revoked}
carol after revoke: {error,revoked} The same steps over REST and MCP
Calls only, against an open server. The create and grant calls were run live with these answers; the handoff calls are written from the route handlers and the registered tool schemas.
# open server (no auth configured)
curl -X POST $B/spaces \
-H 'content-type: application/json' \
-d '{"label":"joint research","owner":"alice"}'
# 201 {"ok":true,"space":"sp_..."}
curl -X POST $B/spaces/$SPACE/grants \
-H 'content-type: application/json' \
-d '{"rights":["read"],"subject":"carol"}'
# 201 {"token":"bsp_...","grant":{...}}
curl -X POST $B/handoffs \
-H 'content-type: application/json' \
-d '{"space":"'$SPACE'",
"task_name":"finish the draft",
"from_agent":"alice","to_agent":"bob"}'
curl -X POST $B/handoffs/accept \
-H 'content-type: application/json' \
-d '{"token":"'$HTOK'","agent":"bob"}'
curl -X POST $B/handoffs/complete \
-H 'content-type: application/json' \
-d '{"token":"'$HTOK'","result":"shipped"}' {"name": "space_create",
"arguments": {"label": "joint research",
"owner": "alice"}}
{"name": "space_grant",
"arguments": {"space": "sp_...", "rights": ["read"],
"subject": "carol"}}
{"name": "handoff_create",
"arguments": {"space": "sp_...",
"task_name": "finish the draft",
"from_agent": "alice", "to_agent": "bob"}}
{"name": "handoff_accept",
"arguments": {"token": "bsp_...", "agent": "bob"}}
{"name": "handoff_complete",
"arguments": {"token": "bsp_...", "result": "shipped"}} Limits to know
- Tokens are checked by the server, over REST and MCP. Inside your own Erlang node,
open_space/1and everybarrel_sessioncall take no token, so any code can open any space (verified). Use per-space encryption if processes must not read each other's data. - Accepting, completing or chaining a handoff only checks the read right on its token.
- A space's vector store lives on one node, at
<data_dir>/<id>_vec, and is not replicated. - Encrypted spaces can be opened through the Erlang API only, not over REST or MCP.
chain/2andcomplete/2are alternatives: aftercomplete, the token is revoked andchainfails.