Roles & Permissions

This page tells you who may do what in noBGP: in your organization, on your networks and on each node. It is the one place that states the rules. Organizations & Teams tells you how to give a role to a person. Node Access Control tells you what a machine refuses on its own.

In short

1. Your organization is your team. Each person in it has one role: Owner, Admin or Member.
2. Whoever creates a network or a node owns it.
3. A node's controllers are its owner and the organization's Owners and Admins. Only they change the node and decide who else may use it.
4. Other members use a node in two ways: the node is shared with the organization, or a controller puts them on the node's access list.
5. Using a node never makes you root. Root is a separate grant, given to a named person after a warning.
6. A service opens for the people it names. A terminal always needs sign-in.
7. The machine has the last word. Settings on the machine can refuse root, commands or files to everyone, Owners included.

The three roles

Role	What it is
Owner	Runs the organization: everything an Admin does, plus billing, SSO and ownership transfer.
Admin	Controls every network and every node in the organization, and manages its members. No billing and no SSO.
Member	Creates networks and nodes, and controls the ones they own. Uses other nodes only when a node is shared or names them.

An organization always keeps at least one Owner. Only an Owner can make another Owner or change an Owner's role.

What you can have on a node

• Use: run commands, open terminal sessions, read and write files, and read the node's network information. All of it runs as the account that the node's owner set on the machine (user).
• Root: use the node as root. On Windows, root means administrator. Root includes use.
• Control: change the node and decide who may use it. This covers its name, labels, where it is on the map, remote configuration, sharing, access list, services, local MCP server, compute, agent log and storage area, and transfer and delete. Only the node's controllers have control. Nobody can give it on the access list.

Being in the same network as a node gives your node a network path to it. It does not let you use it.

node_list tells you what you hold on each node, in my_access (with view: "full"): control, root, use or none.

Who may do what

Owns it is a Member who owns the network or node in that row. Other member is any other Member of the organization. noBGP support applies only while your organization allows support.

You can…	Owner	Admin	Member, owns it	Other member	noBGP support
Organization
See usage and the plan	✓	✓	✓	✓	—
List members and invites, read the audit log, rename the organization	✓	✓	—	—	—
Invite and remove members, change roles 1	✓	✓	—	—	—
Turn noBGP support access on or off, or give it for a time	✓	✓	—	—	—
Billing (card, invoices, credit, spend cap), SSO, transfer the organization	✓	—	—	—	—
Networks
Create a network (you own it)	✓	✓	✓	✓	—
Change its name, channel, Org or Private, isolation, "members may add nodes"	✓	✓	✓	—	—
Delete it 2	✓	✓	✓	—	—
Read, create, disable or delete an enrollment key	✓	✓	✓	—	—
Add a node to it 3	✓	✓	✓	while "members may add nodes" is on	—
Take a node out of it 4	✓	✓	✓	—	—
Read and write its shared drive	✓	✓	✓	✓	—
Nodes
Use the node	✓	✓	✓	if shared or on the access list	✓
Run as root on the node	✓	✓	✓	with a root entry	✓
Read the node's agent log	✓	✓	✓	—	✓
Read and change its remote configuration	✓	✓	✓	—	✓
Rename, label, set where it is, read and write its storage area	✓	✓	✓	—	—
Set it to Private, manage its access list, answer requests	✓	✓	✓	—	—
Ask to use it	—	—	—	✓	—
Turn its local MCP server on or off	✓	✓	✓	—	—
Stop, extend or remove its compute; give it to another member; delete it	✓	✓	✓	—	—
Services
Publish, change, share or delete a service on the node	✓	✓	✓	—	—
Make a web or port service public	✓	✓	—	—	—
Open a service that needs sign-in	✓	✓	✓	if named, or "all org members"	—

The node's own settings apply on top of every row. A ✓ means that noBGP permits the action. The machine can still refuse it. See The node owner's settings.

¹ Only an Owner can bring in another Owner or change an Owner's role. The last Owner cannot leave: transfer ownership first.

² Deleting a network never deletes a node. From router 0.4.211 a network with nodes in it is no longer refused: its nodes leave it and stay, and a node whose last network it was ends up in no network. ⚠ A provisioned machine among them keeps running and keeps billing until somebody stops it.

³ You must also control the node that you add. The network must be in the node's own organization.

⁴ Either side is enough — the network's owner or an Owner or Admin, or the node's owner or an Owner or Admin — because taking a node out of a network removes reach rather than granting it.

Sharing a node with your organization

Sharing is set in two places:

Setting	Values	Who sets it
Network	Org (the default) or Private	the network's owner or an Admin
Node	Follow the network (the default) or Private (you and org admins)	the node's controllers

• A node is shared only when it follows its networks and every network it is in is Org. A node in no network is private. Then every member of the organization may use it, never as root.
• A node can be more private than its network, never more open.
• Private keeps the node to its controllers and its access list. The organization's Owners and Admins are controllers of every node, so Private never locks them out.
• A change is live. A member who used a node only through sharing loses it at their next call, and their running commands stop.
• A change to Org opens only the nodes you control. A node that follows the network but that you do not control is set to Private instead, and the result names it.
• You choose when you create a node, in the app's registration page or compute dialog, or with access on provision_node. A node that joins with an enrollment key follows its network.

Your own computer in a team network

Set it to Private (you and org admins). Your computer still reaches the team's services, and the team cannot run commands on it.

The access list

The access list names members of the node's organization. Each entry is use or root. An entry counts whatever the sharing setting is.

• Ask. A member asks to use one node, or every node of a network. A request is always for use.
• Answer. A controller grants or refuses the request, or adds a member directly.
• Root. A controller gives root to a named member only, after a warning that says what root gives. On MCP the grant needs confirm_root: true — or, from router 0.4.203, your client asks you and sends your answer, where it can. A node with allow-root off refuses the grant. If allow-root goes off later, the entry stays but gives only use.
• Revoke. A controller removes an entry at any time. It takes effect at the member's next call, and their running commands stop. A revoke does not stop use that comes from sharing, and does not remove the member from a terminal's visitor list. The result names each terminal that still admits them.

Somebody who has not joined the organization cannot be on it. Naming them is refused, and from router 0.4.193 the refusal names the organization and the tool that invites them — inviting is an Owner's or an Admin's call, so a Member who controls the machine can grant access on it without being able to bring anyone into the organization. They are a member once they accept.

The node's owner and the organization's Owners and Admins are never on the list, and nobody can remove their access.

Root

Root is the node's most powerful identity: root on Linux and macOS, administrator on Windows. It gives everything on the machine, including the node's own settings and its key.

Who may run as root: the node's controllers, each member with a root entry, each person named on a root terminal (in that terminal only), and noBGP support while your organization allows it. The node's allow-root setting must also allow it. It binds everyone.

The root field on a tool picks the identity. See Execution identity.

The old name: admin

Root was called "admin" or "elevated" before. The old names (admin, admin_used, allow_admin, can_elevate, and allow-admin on the machine) still work — except on the MCP tools, which publish and accept the new names only from router 0.4.195; the REST and OpenAPI surface still takes and returns both, and so does the machine's own config. One old result name can still appear in an MCP result: can_elevate in the orgs list of whoami, beside can_root. Read can_root. Do not send both names of one field in one call: that is invalid_args. Node Access Control tells you what happens on a machine where both setting names are set.

Services

A service makes something on a node reachable at a URL: a web app, a port or a terminal. Only the node's controllers publish, change, share or delete a service.

A service that needs sign-in opens for:

• the node's controllers,
• each address that the service names (for example ana@example.com, or *@example.com), and
• every member of the organization, only when a controller sets the service to all org members. This is never the default.

Anyone else sees a refusal page with a Request access button. The node's controllers approve or decline the request.

An open terminal is checked again while it runs. It closes when the person's access is withdrawn.

A terminal gives a shell to everyone it admits

Each person that a terminal admits gets a shell on the node, as the account that the terminal runs as. Name only people who may have that access.

Public services

• A web or port service can be public (no sign-in, auth_required: false). Only an Owner or Admin can make it public.
• A terminal is never public. It always needs sign-in.

Root terminals

A root terminal opens a root shell. The node's controllers open it without being named. Anybody else must be named on it by exact address, never by a pattern and never through "all org members".

• The name is itself a root grant, in that terminal only. The person needs no root entry, and can be outside the organization. So naming anyone who is not a controller shows the root warning and needs a confirmation (confirm_root: true).
• Removing the name closes the terminal for that person.
• A name stays when the person who added it stops being a controller. It stands until a controller removes it.

A node's storage area

Each node has a storage area in noBGP storage, apart from the network's shared drive. To read or write it, you need control of the node. The node's own settings never see these requests, and the node can later read or run what is put there.

The node's agent log

Reading a node's agent log (node_logs) needs control of the node. Use is not sufficient, and neither is a root entry: the log records every session, setting change and refusal on the machine, other people's included. A member who cannot read it can ask a controller, or read it at the machine with nobgp service logs.

noBGP support

Your organization decides whether noBGP support staff may act in it. "Allow noBGP support" is on by default. An Owner or Admin can turn it off, and then give staff temporary access, for a number of hours, when you want help.

While support is allowed, staff may:

• see your organization and its nodes,
• use a node and run as root on it,
• read a node's agent log, and
• read and change a node's remote configuration (node_config_set).

Staff never do anything else. They never rename, label, share or delete a node, and never change its access list, services or compute. The node's own settings still apply to staff: allow-root: false refuses them, and the node refuses a change to its own settings. Every staff action, and every staff attempt that noBGP refuses, is written to your audit log and marked as noBGP support. When support ends, staff work that is still running stops.

A node's local MCP server

A node can run its own local MCP server, for an assistant on that machine. It is on or off. Only the node's controllers turn it on, and the machine's owner can refuse it with local-mcp: off.

When it is on, it acts for the node's owner, with the owner's current rights, checked at each call. It reaches the nodes of the node's networks that the owner may use, and runs as root only where the owner may. It turns off when the node gets a new owner.

Anyone who can use the node can use its local MCP server

The server listens on the machine. A person who can run commands on the node can call it, and so reach what the node's owner may reach. Turn it on only on a node that you do not share.

Rules that surprise people

• Sharing never gives root. Root comes only from a controller, one person at a time, after a warning.
• A name on a root terminal is a root grant. Removing the name closes the terminal.
• allow-root: false on the machine refuses root to everyone: Owners, Admins, the node's owner and noBGP support.
• noBGP support never goes past your organization's support setting, and never past the machine's own settings.
• The agent log is control. A member who can use a node, even as root, cannot read its log through noBGP.
• An account with sudo gives root. If the node's user can use sudo with no password, or is an administrator, then use of the node gives root in practice. noBGP does not stop this. Before you share a node, set its user to an account without those rights.
• A revoke does not clean up the machine. It closes noBGP's doors only. An SSH key, a scheduled job, a tunnel or a detached process that the person left stays. Root can leave more of these than use.
• A machine installed with the network's enrollment key belongs to the network's owner, not to the person at the machine. Install your own computer with nobgp register and sign in, so that the node is yours and you can set it to Private.
• There are no groups yet. Access is given per node, one person at a time. A node is shared inside its organization only. A service can name people outside it.
• An email address has no case, from router 0.4.204. Ada@example.com and ada@example.com are one person everywhere noBGP matches an address — an invitation, an access request, a node transfer — and two accounts can no longer differ only in case. Before, an access request sent under one spelling and again under the other was two pending requests for one person.

When a member leaves

When a member leaves or is removed, their networks and nodes move to an Owner of the organization: the Owner who removed them, or else the first Owner. Nothing is deleted, and the result lists what moved.

• Their access-list entries are removed.
• The local MCP server of each moved node turns off.
• A moved network keeps its name. From router 0.4.204 a network name is unique inside its organization rather than per creator, so a move within one organization can never collide and nothing is renamed. Earlier routers gave such a network a new name, such as lab-2.

node_transfer gives one node to another member of its organization, named by email. The new owner controls the node, and its local MCP server turns off. The result lists each root grant on the node, so that the new owner knows who else has root.

The node owner's settings

Some settings live on the machine, in the agent's config file. Only a person at the machine changes them, with sudo nobgp config (on Windows, from an administrator shell). They apply to every caller, Owners, Admins and noBGP support included.

Setting	What it controls	Default
allow-root	Whether any work may run as root	on
allow-tools	Which capabilities the node serves: fs, command, logs	all
allow-roots	Which paths the file tools may touch when they do not run as root	/
user	The account that work runs as when it does not run as root	the account that installed the agent, or none on a service install
local-mcp	Whether the node may run its local MCP server at all	on
peer-loopback	Whether other nodes may reach ports bound only on this machine's loopback	on
lan-names	Which host names on the machine's own LAN it serves to its networks	every name

When allow-tools, allow-roots or allow-root refuses a call, the code is permission_denied. A node with no usable user refuses work without root with failed_precondition. Only a change on the machine answers it. Root can edit the settings file, so an owner who wants the last word sets allow-root to off. Node Access Control has the details.

Execution identity

Your access decides who may ask. The execution identity decides what the work runs as. A node offers two identities:

• The configured account (user), which the node's owner sets on the machine. This is use.
• Root: root on Linux and macOS, administrator (LocalSystem) on Windows.

The root field picks between them on command, command_subscribe, file, the fs_* tools, fs_grep_subscribe, service_publish and service_update:

• Omitted (the default): the call runs as the configured account. On a node with no configured account, it runs as root, so you need the right to run as root.
• true runs as root.
• false runs as the configured account. A node with no other account refuses it with failed_precondition. It never runs that call as root instead.

Each result reports root_used when the call ran as root — also when you omitted root and it resolved to root. A call that ran as the configured account reports no root_used at all, and from router 0.4.206 it reports user, the account it ran as, which is the field to read on a mixed fleet where one call lands on a different account per node. On a tool that runs on many nodes in one call, each node resolves its own identity. On a mixed fleet, omit root. node_logs takes the field and ignores it: the node reads its own log as the agent.

The MCP Reference has the per-tool contract.

Node labels

A node's local MCP server can be limited to target nodes by label, and those targets are read live. So a label change can move a node into or out of the reach of another node's local MCP server. For this reason, labelling a node needs control of that node. The role.* label names are reserved, and node_label refuses them for everyone.

What a refusal looks like

Every refusal is HTTP 403. The code tells you whose decision it was:

Code	Whose decision	What to do
forbidden	noBGP, about you	Ask a person who may do it: for a node, one of its controllers; for billing or SSO, an Owner. Drop root if the work does not need it.
permission_denied	the machine	A setting on the machine refuses it, or the account that the call ran as may not read or write that file. Only a change on the machine answers the first case. For the second, run the call as root if you hold root.
failed_precondition	noBGP or the machine, about the state of things	Something must change first. The message says what: for example, send the root confirmation, set an account on the node, or stop the machine before removing the node.

A not found where you expected a refusal means that the object belongs to an organization you are not in. noBGP never tells an outsider what exists. None of these codes is retryable.