Sharing & Permissions
Use board and branch permission settings to control collaboration within your workspace. Application permissions and host filesystem isolation are separate controls. Deployment operators should also read Execution Isolation.
Board and branch permissions
Every board and branch has one primary owner. The current owner or a workspace Admin/Superadmin can use Transfer ownership in its permission settings to choose another member of the same workspace. Managers cannot transfer ownership unless they are also the owner or a workspace administrator. Viewer-only accounts cannot receive ownership. This transfer authority is independent of the configured superadmin bypass for ordinary branch operations.
Transfer changes management ownership of one resource only. A board transfer does not transfer its branches, and a branch transfer does not grant access to its board. Creators and historical authorship stay unchanged. Named access entries, groups, Others, inheritance/overrides, and session-sharing switches are preserved. The former owner loses the primary-owner shortcut but keeps any independent access or administrator privileges. The result shows their remaining resource-policy capabilities and branch file access.
This is not an assistant runtime handoff or offboarding: sessions, schedules, gateway run-as, Knowledge namespace ownership, personal MCP connections, OAuth grants and credentials do not move. Existing work keeps its execution identity; normal authorization rechecks may stop it if that identity loses access. Transfer does not pause work or guarantee immediate credential/process revocation. The successor must configure their own connections. Execution-home Sessions remain unshareable; branch-home Sessions still require both sharing gates.
The REST/Socket.IO commands are PATCH /boards/:id/ownership and
PATCH /branches/:id/ownership, with full UUIDs in the route and body:
{
"expected_owner_user_id": "<current owner UUID>",
"target_user_id": "<successor UUID>"
}Read the resource first. A stale expected owner is rejected; reload before
retrying. Ordinary resource and permission patches cannot change ownership.
MCP exposes agor_boards_transfer_ownership and
agor_branches_transfer_ownership. Bulk transfer, runtime handoff and user
soft/hard deletion are not part of these commands.
Upgrade the daemon and apply its normal database migrations before using transfer. Existing owners are preserved. Transfers require authorization, an eligible successor, and a matching expected owner on both SQLite and PostgreSQL. Branches undergoing maintenance or permanent deletion reject transfer.
A board has two separate settings:
- Board access controls who can see and edit the canvas.
- Branch defaults are the complete permission package inherited by branches on that board.
A branch either inherits that entire package or uses one override copied from the current defaults. This includes session sharing—there is no separate inheritance switch for it.
Board roles are Viewer, Editor, and Manager. Branch roles are:
| Role | Meaning |
|---|---|
| Viewer | View the branch and its conversations |
| Collaborator | View, create Sessions, and prompt branch-home Sessions |
| Manager | Collaborator access plus branch, environment, session-lifecycle, and permission management |
Branch file access is selected separately as none, read, or read/write. Collaborator and Manager can open a terminal only when file access is not none.
Each entry names exactly one person or group. A person’s direct entry overrides their group memberships; otherwise group permissions combine and the highest file access wins. Others is a fallback only for active members of the same workspace who match no person or group entry.
Collaborators and Managers may prompt another person’s branch-home Session only when the workspace preference and effective branch permission package both enable shared session prompting. The task runs as the actual caller while the conversation and native SDK state remain branch-owned. An execution-home Session is never shareable; create a new branch-home Session instead. When a gate is disabled, Agor and connected gateway channels return an actionable, terminal denial rather than silently changing execution identity or retrying.