Barrel
FR GitHub

Spaces and capabilities

When several agents work together, each one needs a place to keep its notes and results, a way to share them with the agents it works with, and a guarantee that it cannot read the work of agents it does not work with. Giving every agent the server's global token gives each of them access to everything. Spaces give each piece of shared work its own database and its own keys.

A space is a Barrel database that agents share by holding a capability token for it: a secret that grants rights on that one space and nothing else. A session is an agent's working context inside a space, with a sliding TTL: it expires after a period without activity. A handoff passes a task, and the token to work on it, from one agent to another. Read this to understand the model before you use the spaces guide, and to know which of these checks protect you in your own process and which only behind barrel_server.

The examples on this page follow one scenario. Alice creates a space for a joint research draft, gives Carol read-only access, works on the draft in a session, then hands the task to Bob to finish.

The pieces

PieceWhat it isWhere it lives
SpaceA database named sp_ plus 16 characters, with a registry entryIts own database; the entry in _barrel_spaces
Capability tokenbsp_..., scoped to one space, with rightsShown once; only its SHA-256 hash is stored
SessionA working context with messages, data and pinsDocuments in the space, expiring by TTL
HandoffA task plus a token for its spaceThe registry, so it can be listed

Since only the hash of a token is stored, Barrel cannot show you a token again. Keep it when you grant it, and grant a new one if it is lost.

Rights

Each token carries rights that say what its holder may do in the space. Rights form a ladder: read < write < admin. A higher right includes the lower ones.

RightOver barrel_server it allows
readGETs, changes, query, search, and the replication reads (pull)
writeDocument and attachment writes, and the replication writes (push)
adminGranting, listing and revoking tokens; creating handoffs for the space

A token never reaches another space, database lifecycle (PUT and DELETE /db/:db), or _timeline routes: those answer 403.

Create a space and grant a token

Alice creates the space and grants Carol a read token. The last two lines check what Carol's token allows: a write in the space, then a read in another space.

Erlang shell
{ok, _} = application:ensure_all_started(barrel_spaces),
{ok, #{id := SpaceId} = Space} =
  barrel_spaces:create_space(#{label => <<"joint research">>,
                               owner => <<"alice">>,
                               vectordb => none}),
{ok, ReadTok, _} = barrel_caps:grant(SpaceId,
  #{rights => [read], subject => <<"carol">>}),
barrel_caps:verify(ReadTok, SpaceId, write),
barrel_caps:verify(ReadTok, <<"sp_other">>, read).
Output from a run on barrel_spaces 1.3.1
{error,forbidden}
{error,wrong_space}
What just happened

Both checks fail, each for its own reason. forbidden means the token is valid for this space but does not carry write. wrong_space means the token belongs to another space, whatever its rights.

barrel_caps:revoke/1 ends one token; barrel_spaces:drop_space/1 ends the space and revokes every token for it.

Sessions

A session is where an agent keeps what it is doing: the conversation so far, small pieces of state, and pins, the facts it must keep in view. A session belongs to an agent and expires after ttl seconds without a touch (the space default is 3600). It holds messages, key/value data and pinned context, all stored as documents in the space, so any holder of a token for the space can read them.

Erlang shell
{ok, Sid} = barrel_session:create(Space,
  #{agent => <<"alice">>, ttl => 1800}),
{ok, _} = barrel_session:add_message(Space, Sid,
  #{role => <<"user">>, content => <<"draft is half done">>}).

Here Alice opens a session that expires after 30 minutes without activity, and records where the draft stands.

Handoffs

A handoff is how Alice gives the rest of the task to Bob without copying anything. A handoff issues a token for the space (rights read and write by default) and returns it once. Whoever presents it accepts: the handoff flips from pending to accepted, a second accept fails, and the acceptor gets a session in the same space. Nothing is copied; the context is read in place.

Erlang shell
{ok, #{token := HTok}} = barrel_handoff:create(Space,
  #{task_name => <<"finish the draft">>,
    from_agent => <<"alice">>, to_agent => <<"bob">>,
    from_session => Sid}),
{ok, #{session := BobSid}} =
  barrel_handoff:accept(HTok, #{agent => <<"bob">>}),
barrel_handoff:accept(HTok, #{agent => <<"mallory">>}),
{ok, _} = barrel_handoff:complete(HTok,
                                #{result => <<"shipped">>}),
barrel_caps:verify(HTok, SpaceId, read).
Output from a run on barrel_spaces 1.3.1
{error,already_accepted}
{error,revoked}
What just happened

Bob accepts first and gets his own session. Mallory, presenting the same token, gets already_accepted. Once Bob completes the task, the token is revoked, so a later check returns revoked.

Completing a handoff revokes its token by default. chain/2 hands it on instead; use one or the other, not both.

Across nodes

Spaces and the registry replicate like any database. Since barrel_spaces 2.0 each fact is a document of its own, so nodes that write at the same time never lose each other's writes: a revocation holds on every node, session keys and pins written on two nodes are both kept, a removed key or pin stays removed, and a handoff never goes back to an earlier status. When two agents accept a handoff on nodes that cannot see each other, every node names the same owner: the earliest accept. See Spaces, sessions, handoffs for the rules, and Upgrade to docdb 3 and spaces 2 to move a mesh from 1.x.

In process and behind the server

Where the token is checked decides how much it protects you. Inside your own Erlang node, every piece of code can reach every database, so a token is only as strong as the code that checks it. Behind barrel_server, the server checks it on every request.

Limit

In your own Erlang node, tokens are advisory. barrel_spaces:open_space/1 and every barrel_session call take no token, so any code in the node can open any space. barrel_caps:grant/2, revoke/1 and barrel_handoff:create/2 do not check for admin. Per-space encryption is the only isolation in process.

CheckIn process (barrel_spaces)barrel_server REST and MCP
A token is valid, not revoked, not expiredwhen you call barrel_caps:verify/3on every request
The token's space matches the databasewhen you call verify/3yes, 403 otherwise
read / write per operationwhen you call verify/3yes, per route or per tool
admin to grant, revoke, create a handoffnoyes
Accepting or completing a handoffneeds only read on the tokenneeds only read on the token

So: when agents must not reach each other's data, run them against barrel_server with capability tokens, and keep the global token away from them. The same tokens work over REST and MCP. See Authentication.

Notes

  • Grants and handoffs live in the registry database _barrel_spaces. Replicating it makes a token minted on one node verify on another; revocation then travels at replication speed.
  • A space's vector store is per node and not replicated.
  • Encrypted spaces are available from Erlang only: the server cannot pass a key spec when it opens a space.

Written for the site Edit this page View as Markdown

Up and down to moveEnter to open