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
| Piece | What it is | Where it lives |
|---|---|---|
| Space | A database named sp_ plus 16 characters, with a registry entry | Its own database; the entry in _barrel_spaces |
| Capability token | bsp_..., scoped to one space, with rights | Shown once; only its SHA-256 hash is stored |
| Session | A working context with messages, data and pins | Documents in the space, expiring by TTL |
| Handoff | A task plus a token for its space | The 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.
| Right | Over barrel_server it allows |
|---|---|
read | GETs, changes, query, search, and the replication reads (pull) |
write | Document and attachment writes, and the replication writes (push) |
admin | Granting, 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.
{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). {error,forbidden}
{error,wrong_space} 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.
{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.
{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). {error,already_accepted}
{error,revoked} 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.
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.
| Check | In process (barrel_spaces) | barrel_server REST and MCP |
|---|---|---|
| A token is valid, not revoked, not expired | when you call barrel_caps:verify/3 | on every request |
| The token's space matches the database | when you call verify/3 | yes, 403 otherwise |
read / write per operation | when you call verify/3 | yes, per route or per tool |
admin to grant, revoke, create a handoff | no | yes |
| Accepting or completing a handoff | needs only read on the token | needs 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.