Agent Pools

What is a Pool?

An Agent Pool groups profiles that need to collaborate through shared state. Pools add two things to each member profile:

A role-aware filesystem policy under /pools/{pool}/...
Pool tools: pool_info, pool_post, and pool_inbox

Pool membership does not replace the profile sandbox. Every profile still keeps its implicit home at /agents/{self}/**; pool access is layered on top.

Pool Schema

type AgentPool struct {
  ID          string
  Name        string
  Description string
  Members     []PoolMember
  FS          *PoolFSPolicy
}

type PoolMember struct {
  Profile string
  Role    string // "lead" | "member" | "observer"
}

Roles default to member when omitted or unknown.

Creating a Pool

curl -X POST https://api.orcapods.ai/api/pools \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "research-team",
    "description": "Shared workspace for market research",
    "members": [
      { "profile": "researcher", "role": "lead" },
      { "profile": "reviewer", "role": "member" },
      { "profile": "auditor", "role": "observer" }
    ],
    "fs": {
      "read": ["/datasets/**"],
      "write": ["/pools/{pool}/sot/**"],
      "deny": ["/pools/{pool}/archive/private/**"]
    }
  }'

The conductor broadcasts pools to all runners, just like profiles.

Built-in Path Layout

Every pool uses the same directory conventions:

Path	Purpose
`/pools/{pool}/sot/`	Shared source-of-truth documents
`/pools/{pool}/board/public/`	Public blackboard for all members
`/pools/{pool}/board/public/posts/`	Markdown posts created by `pool_post`
`/pools/{pool}/board/private/{self}/`	Member-private workspace
`/pools/{pool}/archive/`	Shared archive

pool_info returns the concrete paths for the active session.

Role Permissions

Role	Read	Write	Delete
`lead`	`sot`, public board, all private boards, archive	`sot`, public board, all private boards, archive	`sot`, board, archive
`member`	`sot`, public board, own private board, archive	public board, own private board	own private board
`observer`	`sot`, public board, archive	none	none

Custom fs.read, fs.write, fs.delete, and fs.deny entries are additive. deny always wins.

Pool Tools

@pool is part of @default, so normal profiles can inspect pool membership immediately. Tools that read or write posts use the runner’s VirtualFS dispatcher; with no VFS_* environment they still work in that runner’s in-memory storage, but posts are not shared with vfs serve or other runner processes.

Tool	Description
`pool_info`	Returns pool memberships, role, roster, and path layout
`pool_post`	Writes a markdown post to `/pools/{pool}/board/public/posts/`
`pool_inbox`	Lists recent public posts; use `read_file` to fetch a full post

Typical agent workflow:

Call pool_info to discover memberships and paths.
Call pool_inbox to catch up on recent public posts.
Use read_file / write_file for shared documents.
Call pool_post for updates other members should see.

Effective Filesystem Policy

The runner compiles a session policy in this order:

Implicit home grant: /agents/{self}/**
Profile fs grants and denies
Built-in pool grants for each membership role
Pool custom fs grants and denies

Tokens are substituted before matching:

Token	Value
`{self}`	Current profile name
`{pool}`	Pool name
`{role}`	Member role

Relative paths in read_file, write_file, and delete_file resolve under /agents/{self}/. Use absolute paths for pool files.

Get Started

Core Concepts

Guides

Agent Pools

What is a Pool?

Pool Schema

Creating a Pool

Built-in Path Layout

Role Permissions

Pool Tools

Effective Filesystem Policy

​What is a Pool?

​Pool Schema

​Creating a Pool

​Built-in Path Layout

​Role Permissions

​Pool Tools

​Effective Filesystem Policy

What is a Pool?

Pool Schema

Creating a Pool

Built-in Path Layout

Role Permissions

Pool Tools

Effective Filesystem Policy