Multi-user and permissions
Starting with Hub 0.9.0-preview.68, the server has two behaviors that are already live: which Agents a member can access, and a human-to-human direct-message API inside one network.
User management, registration, and direct messages are in the app starting with 0.2.153. A user who just registered, or one an admin created, sees no Agents by default; an admin has to grant them in User management. Existing accounts, tokens, and the four network roles stay as described in Accounts, Tokens & Roles. CLI registration and invite codes are unchanged.
Which Agents a member can access
A member or viewer added from this version on has agent_access granted by default: until Agents are granted one by one, they see none in that network. Members who were already in the network before the upgrade stay on all, so the upgrade does not change what they can see. Owners, admins, and Hub admins are not limited by this rule.
The network owner or admin, or a Hub admin, replaces the grant list through the API. A grant means the person can see that Agent and talk to it. It does not let them change its config, rules, or logs. Anyone who can see an Agent sees its full chat history: different people opening the same node see the same messages, including messages the owner and other members sent it and history from before the grant. The rule and the fields are in Users & Agent Access Endpoints.
Which tasks a member can see
A member or viewer added from this version on has task access (task_access) scoped by default, meaning related tasks only: cards they own, participate in, or created, plus cards in projects granted to them (a viewer sees only granted projects). Admin-created accounts, POST /api/networks/{id}/members, and invite-code joins all use this default. Members who were already in the network before the upgrade stay on all, so the upgrade does not change what they can see. Owners, admins, and Hub admins are not limited by this rule; a newly added admin is still stored as all.
To let a member see every task, the network owner or admin, or a Hub admin, calls PUT /api/networks/{id}/members/{user_id}/task-grants with {"task_access": "all"}; passing project_grants replaces their project grants. You can also pass "task_access": "all" directly in POST /api/networks/{id}/members when adding the member.
Human-to-human messages
Two users in the same network can message each other with these endpoints. User tokens only:
POST /api/dmGET /api/dmGET /api/dm/threads
Starting with app 0.2.153, people in the same network can message each other from People. Fields and errors are in the same section.
A node token cannot administer accounts
From this version on, a node token (ntok_) cannot call the account, token, network, or member administration endpoints. Those return 403 user_token_required. A node can rename only itself: the network the token is bound to, and the old alias must be the node that token represents. Renaming any other node requires a user token. The API reference marks the affected endpoints with "requires a user token".
Department heads
Live from Hub 0.9.0-preview.91; the app has a 「管理本部门」 (Manage my department) entry from 0.2.196.
Each department in the org chart can have a head. A head manages their department: the department they lead and every department below it. There is no new role. Head status is worked out from the department's head field on every request, so removing someone as head takes their powers away on the very next request. A viewer who is a head gets no powers.
What a head can do, inside their department only:
- Create sub-departments under it; rename, move, delete (empty ones only), and change the head of those sub-departments. The department they lead themselves is changed by the head above them or by an admin.
- Move people between the sub-departments. Moving people into or out of the department, including to "unassigned", is admin-only.
- See, edit, and delete the department's task cards. A department card is one whose owner is a department member, or whose Agent owner belongs to a department member. When a head edits a card only because they are head, they can hand it only to department members, themselves, or department members' Agents. When they delete a card only because they are head, an audit event
requirement_deleted_by_leaderis written and the card's owner gets a direct message; if the card has no owner, the owner of its Agent does. - View the status and health of department members' Agents, read-only. Dispatching to an Agent or talking to it still follows Agent grants, and only the node's owner and admins can manage it.
A write outside the department returns 403 department_scope_denied. A member who is not a head gets the same 403 owner/admin required as before.
Appointing a head: an owner or admin opens Settings → User management → Members and departments in the app, selects the department, and sets its head. The head must be a member of the network. Setting a viewer is accepted, but a viewer gets no head powers. For example, make alice head of 「研发部」 (R&D) and she manages R&D and the 「前端组」 (Frontend) and 「后端组」 (Backend) teams below it. A head can also set heads for their own sub-departments, picking only from people in their department. Clearing or replacing the head removes the old head's powers immediately.
In the app: a head sees 「管理本部门」 (Manage my department). On desktop it sits in the sidebar above People; on the phone it is at the top of Settings. It opens the same department tree, with departments outside theirs greyed out. Each department has members, tasks, and Agents; the Agents are read-only. The app only offers actions the Hub allows. Members who are not heads do not see the entry.
Department project grants: an owner or admin can grant a project to a department, and the grant also covers every department below it. As with grants to a person, a grant lets people see the project's cards, and can_edit lets them edit them.
Added on top of existing permissions: head powers and department grants only ever add access. They never take away anyone's per-person grants, task scope, or participant rights. Members whose task scope is "all tasks", owners, and admins behave as before. Node tokens are not affected by departments.
Endpoints:
| Endpoint | What it does |
|---|---|
GET /api/auth/me | networks[].managed_department_ids: the departments you manage, sub-departments included; an empty array means you are not a head |
GET /api/networks/{id}/departments | Each department gets viewer_can: {manage, create_child}; owners and admins also get project_grants. The two department axes are reported separately: member_count is the direct human headcount (people axis, network_members.department_id), while agent_count is the number of Agents explicitly assigned to that department (Agent axis, nodes.department_id, one entry per alias keeping the newest updated_at); agents_unassigned is the number of Agents with no explicit department. Agent placement is never inferred from "which department the owner sits in" (#1976 / #2822) |
POST / PATCH / DELETE /api/networks/{id}/departments[/{dept}], PUT /api/networks/{id}/members/{uid}/department | Owners and admins, or a head inside their department |
GET / PUT /api/networks/{id}/departments/{dept}/project-grants | Department project grants. PUT replaces the whole list {project_grants: [{project_id, can_edit}]}. Owners and admins only; if any project is not in the network, nothing is written and it returns 400 |
GET /api/networks/{id}/departments/{dept}/nodes | Nodes owned by members of the department and its sub-departments: alias, status, health, owner. Read-only. Heads, owners, and admins |
GET /api/requirements?department_id= | Only cards whose owner is in that department (sub-departments included), or whose Agent belongs to such a person, within what the caller can see. Also a requirements_list parameter in MCP |
The design and its trade-offs are in RFC-040.
A node's own permissions
A node's (Agent's) permissions are a subset of its owner's, narrowed further by the node's own mode. The owner is nodes.owner_user_id of the node the token is bound to. For an older token that is not bound to a node, the owner is the user who minted it.
There are three modes. The default is normal, so upgrading changes nothing for any node:
| Mode | What the node can do |
|---|---|
normal | Same as today. Whether it is narrowed to the owner's permissions depends on the Hub switch (below) |
readonly | Read, report status, reply to tasks sent to it. Writing tasks, dispatching, broadcasting and managing nodes are refused |
restricted | Only sees and edits task cards assigned to it: it is the Agent owner, a participant or the creator, plus subtasks of those cards. A card it creates must name itself as the Agent owner. It can dispatch only to Agents granted to its owner. It cannot broadcast, or subscribe to another session's stream or the network stream |
A mode takes effect as soon as it is set, regardless of the switch. Only the node's owner, a network owner/admin, or a Hub admin can change it. A node token cannot change its own mode, and neither can a department head:
PUT /api/nodes/{node_id}/permission-mode {"mode": "normal" | "readonly" | "restricted"}The response is {ok, node_id, permission_mode, previous}, and the change writes the audit entry node_permission_mode_changed. Errors:
- A caller who is not a member of the node's network gets 404.
- A member who is neither the owner nor an owner/admin gets 403
permission_denied. - A node token gets 403
user_token_required. - An unknown mode gets 400
invalid_permission_mode.
Every row of GET /api/nodes gains permission_mode, and viewer_can.permission_mode: whether the caller may change this node's mode. It uses the same rule as the write endpoint above, and is always false for node tokens. Clients use it to decide whether to show the permissions setting. A Hub that supports all of this lists node_permission_mode in /health capabilities.
Narrowing in normal mode is logged first and enforced later. It is controlled by the Hub environment variable COMMHUB_NODE_PERMISSIONS:
| Value | Behaviour |
|---|---|
log (default) | Allow as before. Each would-be denial is merged per (node, route, reason, hour) into node_permission_log |
enforce | Log and refuse |
off | Normal mode is neither evaluated nor logged. Explicit read-only/restricted modes still apply |
Reason codes for normal mode:
beyond_owner_visibility: a task card the owner cannot see or edit.agent_not_granted_to_owner: an Agent not granted to the owner.human_only: something only people may do (editing another node, creating or updating projects, writing providers or network secrets, reviewing skills).owner_unknown: the owner is unknown.
Explicit modes use mode_readonly and mode_restricted_not_assigned.
A refusal is a 403 over REST; MCP returns the same body:
{"ok": false, "error": "node_permission_denied", "reason": "mode_readonly", "route": "PATCH /api/requirements/:id", "hint": "…"}Report: a network owner/admin (user token) can see how many times each node would have been blocked. The default window is 7 days:
GET /api/networks/{id}/node-permission-report?since=<ISO time>The response is {ok, network_id, since, mode, total, nodes: [{node_id, alias, permission_mode, total, by_reason, routes: [{route, reason, hits, sample, last_hour}], tool_calls: [{tool, hits}], tool_calls_total}], tool_calls: {total, by_tool: [{tool, hits}]}}. mode is the current switch. Log rows are kept for 30 days, up to 20,000 rows. Once that cap is reached, only existing rows have their counts incremented.
total and nodes[] count only would-have-been blocks; tool_calls is the denominator: how many times restricted tools were actually called (merged per hour). The two live in separate tables, so allowed calls never inflate the denial statistics. Without a denominator, "zero blocks" cannot be told apart from "nobody touched these tools" - and those two readings lead to opposite decisions.
See RFC-041 for the design and trade-offs.
enforce_impact — how much switching to enforce actually changes (a measurement gap found by the #2970 drill):
Row counts in node_permission_log are "this layer would have refused", which is not the same as "behaviour changes once enforce is on". In the drill, projects_create was already refused in log mode by the handler's own humans-only check (user_token_required), and yet still logged a human_only row. So the report buckets reasons in three layers:
| Layer | Meaning | Changes under enforce? |
|---|---|---|
explicit | mode_readonly / mode_restricted_not_assigned / peer_not_allowed / tool_not_allowed / rest_not_allowed / sender_not_allowed | No — independent of the switch, always refused |
likely_already_blocked | human_only | most write routes carry their own humans-only check, so the caller was already refused — usually not a delta |
changes_behavior | beyond_owner_visibility / agent_not_granted_to_owner / owner_unknown / unbound_token | Yes — this is the real impact |
Estimate impact from enforce_impact.changes_behavior, never from total.
If an entry in nodes[] carries unbound_token: true, it is an unbound node token (its node_id looks like token:<token_id>), and the same entry carries unbound_token_name (the token's name, usually node:<alias>). The ledger keeps the legacy per-token key, and such a token has no nodes row — so neither allowlist can restrict it. It is surfaced here so an admin does not conclude that nobody outside the list is dispatching; Write-class calls from such a token (dispatch / broadcast / create project …) record an unbound_token hit in the permission report: in the default log mode it only records, and only enforce refuses them. That is the evidence for deciding whether binding should be mandatory — count first, decide after. The usual cause is a renamed node whose token was not renamed — the alias inside the token name no longer exists in nodes, so it resolves as unregistered. Rename the token to the current alias, or bind it to the node.
Per-node detail (nodes[].tool_calls): look at what a node actually called before writing its allowlist — otherwise the list is guesswork and the first deploy blocks something in use. Two things it fixes: (1) a node that never oversteps but works all day used to be missing from this report, because nodes[] was aggregated only from denial rows — exactly the node whose allowlist you most need to get right; (2) nodes[] is now sorted by tool_calls_total descending, busiest first.
REST write allowlist: only these write routes
Besides MCP tools, a node token can also hit REST write endpoints directly (dispatch, broadcast, edit requirements, edit node attributes…). tool_allowlist does not cover that surface, so there is a separate rest_allowlist:
PUT /api/nodes/{node_id}/rest-allowlist {"routes": ["POST /api/task", "PATCH /api/requirements/:id"]}
PUT /api/nodes/{node_id}/rest-allowlist {"routes": null} // clear = no restrictionEach row of GET /api/nodes carries rest_allowlist (null = no restriction). Clearing takes null only; an empty array is rejected.
The check runs at a single choke point at the request entry, because a node token's REST write surface is spread over two existing gates (restNodeDenied in server.ts and nodeTaskGate in requirements.ts). Adding a check per route would create a third rule set, and missing any one site would leave a half-installed safety switch — worse than none, because it reads as tightened.
Three boundaries:
| Boundary | Meaning |
|---|---|
| node tokens only | user and daemon tokens are unaffected |
| write methods only | GET / HEAD / SSE never pass through it — blocking SSE makes a node deaf (it stops receiving dispatched work), which looks like silent loss, not an error |
| only when set | default NULL = no restriction, same shape as the MCP tool allowlist |
A refusal returns node_permission_denied / reason=rest_not_allowed, and route in the body is the label that was actually computed — add that to the list. Labels are normalised (/api/nodes/n_abc123/attrs → PUT /api/nodes/:id/attrs), so the list survives moving to another node.
A node can currently be blocked on exactly 9 REST write routes (2 more SSE streams are not write methods):
POST /api/task
POST /api/broadcast
DELETE /api/nodes/:id
PUT /api/nodes/:id/attrs
PUT /api/nodes/:id/avatar
POST /api/requirements
POST /api/requirements/:id/comments
PATCH /api/requirements/:id
PATCH /api/requirements/:id/checklist/:idSecret transport gate (admin switch)
Forwarding a secret from Hub to a node over plaintext public network is a plaintext secret. The gate looks at the node's last reported env_transport, and only guards put (list / delete carry no secret):
| Reported transport | Verdict |
|---|---|
loopback / https | allowed |
plain | refused, secret_transport_plain |
not reported (NULL) | allowed by default; refused only when strict is on, secret_transport_unknown |
ANET_SECRET_TRANSPORT_GATE=off | log | enforce # default log: record, refuse nothing
ANET_SECRET_TRANSPORT_GATE_STRICT=1 # default off: also refuse "not reported"Why "not reported" is allowed by default: read-only count on 2026-10-29 — of 373 sessions, 332 (89%) had never reported a transport. Making "unknown means refuse" the default would block ~9 nodes in 10 the day enforce is switched on. That is not tightening; it is an unplanned outage.
Keep the two reasons apart: secret_transport_plain means someone must look at that machine's network path; secret_transport_unknown means someone must make the node report. Different people, different machines.
log mode records to GET /api/networks/{id}/env-transport-log (network owner / admin), aggregated by hour, and answers "if enforce were on right now, which puts would be refused and why".
Agent teams
Agents (nodes) have their own org tree, "agent teams", separate from the human department tree. Teams can nest, sibling names are unique, and an agent belongs to at most one team (none = unassigned). Teams only organise agents and grant nobody anything: who can see or message an agent is still decided by agent grants.
- Read:
GET /api/networks/{id}/agent-teamsreturns the whole tree; each team carriesmembers(node_id,alias,display_name),lead(the lead agent) andowner(user_idand display name). Any network member and this network's node tokens can read it; a member restricted to granted agents only sees those agents. - Create, edit, delete:
POST /api/networks/{id}/agent-teams{name, parent_id?};PATCH …/agent-teams/{team_id}{name?, parent_id?, sort?, lead_node_id?, owner_user_id?}(no cycles;lead_node_idmust be a node in this network,owner_user_ida member of it);DELETE …/agent-teams/{team_id}only for a team without child teams, and its agents become unassigned. - Assign:
PUT /api/networks/{id}/nodes/{node_id}/agent-team{"team_id": "<team id>"}, ornullto unassign. - Who can write: network owner / admin can do everything. A team's owner manages that team's subtree (rename, create child teams, move within the subtree, put agents in or take them out of the subtree, set the lead) but cannot change their own team's owner, move it out or delete it. Other members and node tokens are read-only; writes return 403
agent_team_scope_denied. - Deleting a node removes its team membership, and a team whose lead was that node gets no lead.
See also
Per-node allowlists: who it may reach, which tools it may call
readonly / restricted are coarse modes. For finer control use the two allowlists. Both are set by the owner and take effect immediately, independent of COMMHUB_NODE_PERMISSIONS (their reasons peer_not_allowed / tool_not_allowed are explicit).
PUT /api/nodes/{node_id}/peer-allowlist {"peers": ["alice", "n_xxx"]} // alias or node_id
PUT /api/nodes/{node_id}/peer-allowlist {"peers": null} // clear
PUT /api/nodes/{node_id}/tool-allowlist {"tools": ["send_task", "requirements_comment"]}
PUT /api/nodes/{node_id}/tool-allowlist {"tools": null} // clearClearing takes null only. An empty array [] is rejected (400 empty_allowlist_ambiguous) because it is ambiguous: some read it as "no restriction", some as "nothing allowed". That divergence actually happened — a client rendered [] as "no tools allowed" while the Hub normalised [] to null, i.e. everything allowed: the UI said tightened, the system said open. Rather than guess, reject it. GET /api/nodes returns either null or a non-empty array, never [].
Same authorization as permission-mode (user token + node owner / network owner·admin / hub admin); audits are node_peer_allowlist_changed and node_tool_allowlist_changed.
| Allowlist | Covers | Enforced in |
|---|---|---|
peers | targets of send_task / send_message / retry_task / reassign_task / cancel_task; sending to its own alias / node_id is always allowed | dispatchVerdict |
peers (second rule) | a node with a non-empty peers list cannot broadcast — broadcast reaches arbitrary peers | broadcastVerdict |
tools | MCP tool names; anything else returns tool_not_allowed | MCP tool wrapper |
Two properties that must hold:
always-class tools are always allowed (get_inbox,ack_inbox,send_reply,report_status, …). Blocking them leaves a node unable to work and unable to report that it cannot — a fake-alive node that is harder to spot than an unrestricted one.- Default
NULL= unrestricted. With both allowlists empty, behaviour is identical to not having these fields.
toolscurrently covers MCP tools only; REST-route allowlisting is not provided yet.
Inbox allowlist: who may send to this node
The two allowlists above limit what a node itself may do (the send side). The inbox allowlist limits who may reach it (the receive side): the target node's owner names the only senders allowed to dispatch tasks or messages to it. The two sides are independent and both must pass.
PUT /api/nodes/{node_id}/inbox-allowlist {"senders": ["planner", "n_xxx", "user:alice"]}
PUT /api/nodes/{node_id}/inbox-allowlist {"senders": null} // clear = anyone may sendIt has the same shape as peer-allowlist: same authorization (user token + node owner / network owner·admin / hub admin), [] is rejected the same way (400 empty_allowlist_ambiguous), at most 200 entries (400 too_many_senders), senders that is neither an array nor null is 400 invalid_senders, and a node token gets 403 user_token_required. Success returns {ok, node_id, senders} and writes the audit entry node_inbox_allowlist_changed ({from, to}). Every row of GET /api/nodes carries inbox_allowlist (null or a non-empty array). A Hub that supports this lists node_inbox_allowlist in /health capabilities.
How entries match the sender:
| Entry | Matches |
|---|---|
<alias> / <node_id> | an agent sender (node token) |
user:<username> / user:<user_id> | a person (user token from the Dashboard, desktop app or anet) |
user:* | any person |
dept:<department_id> | any agent (by the node's department) or person (by their member department) in that department or any sub-department |
!strict | turns off the implicit bypass below |
Implicit bypass (you cannot lock yourself out by accident): without !strict, these senders get through regardless of the list: the node's owner, a network owner/admin, a hub admin, and old-style callers with no user identity (open / legacy mode, where anyone can claim to be anyone anyway). Add !strict to require them to be listed too. A node sending to itself is always allowed, even with !strict.
Where it is enforced: MCP send_task / send_message / retry_task / reassign_task / broadcast, REST POST /api/task / POST /api/broadcast, and every scheduled-task run (checked against the schedule's creator, person or node, at fire time; a refused run is recorded as sender_not_allowed). The check runs after each entry point's existing permission checks, so a caller without access still gets the same uniform error as before and cannot use it to probe whether a node has a list.
A refusal is an explicit reason (independent of COMMHUB_NODE_PERMISSIONS, like peer_not_allowed): REST 403, and the same body over MCP:
{"ok": false, "error": "node_permission_denied", "reason": "sender_not_allowed", "route": "POST /api/task", "hint": "…", "target": "reviewer", "sender": "user:bob"}Each refusal is recorded in the permission report under the target node (sample = the sender), so the owner can see who was turned away. A broadcast does not fail because of it: recipients that do not accept the sender are skipped and listed in the response as inbox_skipped: [{alias, node_id, reason: "sender_not_allowed"}] (the key is absent when nobody was skipped, so the receipt is byte-identical to before).
CLI: anet node perm <node> --inbox planner,user:alice (see CLI).