Barrel
FR GitHub

A database per agent

Give each agent its own database and decide, per agent, what it may read and write. When an agent misbehaves or its job is done, revoke its token; nothing else is touched.

Built from spaces and capability tokens, enforced by barrel_server on REST and MCP. Runs on one node with no other service.

The problem

Several agents writing to one shared database step on each other's data, and every access rule lives in your prompt or your glue code. Taking one agent's access away, or cleaning up after it, means finding its rows.

How it fits together

  1. Planner (admin token)

    • space_create one space per agent
    • space_grant read and write, for one subject
  2. creates and grants
  3. barrel_server

    • sp_research the researcher’s database
    • sp_writer the writer’s database
  4. token over MCP
  5. Agents (their own token each)

    • Research agent MCP, bearer bsp_…
    • Writer agent MCP, bearer bsp_…

The planner holds an admin token and creates one space per agent. Each agent connects to /mcp with its own token; the server refuses a token used on another space or without the right it needs.

Build it

Six steps against a running barrel_server. Each MCP request is a tools/call sent to POST /mcp after the usual initialize.

  1. Start the server with auth on

    Every request then needs a token. The admin token is yours; agents never see it.

    sys.config
    [{barrel_server, [
       {http_port, 8080},
       {auth, #{tokens => [<<"admin-token">>]}}
     ]}].
  2. Create a space for the agent

    The planner calls space_create with the admin token. A capability token cannot create spaces.

    {"jsonrpc":"2.0","id":3,"method":"tools/call",
     "params":{"name":"space_create",
      "arguments":{"label":"research","owner":"planner"}}}
    REST response, from a recorded run
    HTTP/1.1 201 Created
    {"ok":true,"space":"sp_wh2tq2ocmemj52ln"}
  3. Grant it a token

    The token is returned once; only its hash is stored. Hand it to the agent and keep the token_id to revoke it later.

    {"jsonrpc":"2.0","id":4,"method":"tools/call",
     "params":{"name":"space_grant",
      "arguments":{"space":"sp_…",
                   "rights":["read","write"],
                   "subject":"researcher"}}}
    REST response, from a recorded run with a read grant (wrapped, token shortened)
    {"token":"bsp_cc36jf4gfrnkk6sm_ps5i…",
     "grant":{"id":"grant:cc36jf4gfrnkk6sm",
      "token_id":"cc36jf4gfrnkk6sm",
      "rights":["read"],"subject":"agent-1",
      "space":"sp_wh2tq2ocmemj52ln",
      "expires_at":0,"revoked_at":0,"type":"grant", …}}
  4. The agent works in its space

    It connects to /mcp with its own token as a bearer and writes to the space database. The write is recorded with the agent as actor.

    MCP request from the research agent
    {"jsonrpc":"2.0","id":8,"method":"tools/call",
     "params":{"name":"doc_put",
      "arguments":{"db":"sp_…",
       "doc":{"id":"note-1",
              "title":"sources for Q3 report"}}}}
    Response shape, from a recorded run (wrapped, rev shortened)
    data: {"id":8,"jsonrpc":"2.0","result":{"content":[
      {"type":"text","text":"{\"id\":\"note-1\",
      \"ok\":true,\"rev\":\"000001a1…\"}"}]}}
  5. Other databases stay closed to it

    The same token on another database is refused: 403 over REST, a tool result with isError over MCP. So is a write with a read-only grant.

    REST
    curl -H 'authorization: Bearer bsp_…' \
      localhost:8080/db/demo/doc/a
    From a recorded run
    HTTP/1.1 403 Forbidden
    {"error":"forbidden"}
  6. Revoke the token when the job ends

    Revocation is immediate on this node. The space and its data stay for the next agent or for review.

    {"jsonrpc":"2.0","id":9,"method":"tools/call",
     "params":{"name":"space_revoke",
      "arguments":{"space":"sp_…",
                   "token_id":"cc36jf4gfrnkk6sm"}}}

What Barrel does

  • Creates and drops each agent’s database
  • Issues, checks and revokes tokens with read, write or admin rights
  • Keeps sessions and messages per agent, with expiry
  • Records who wrote what, in which session

What your application does

  • Decides which agent gets which space and rights
  • Stores each token where only that agent can use it
  • Runs the agents and their model calls
  • Calls revoke when a job ends

Limits

  • Tokens are enforced by the server. Code inside your own Erlang node can open any space without one; give spaces their own encryption keys if they must not read each other.
  • Each space is a full database with its own files on disk. Idle spaces close themselves, but size the node for the spaces you keep open at once.
  • A space’s vector store stays on the node that built it; replicate the documents and rebuild it elsewhere.
  • A capability token reaches the space itself only, not branches of that space.
  • Over REST and MCP, spaces open with default options, so encrypted spaces are Erlang API only for now.

Go further

Up and down to moveEnter to open