Operator Scopes for Gateway Clients

Operator scopes determine what a Gateway client is permitted to do once authentication succeeds. These act as a control-plane safeguard within a single trusted Gateway operator domain, not as isolation for hostile multi-tenant environments. To achieve strong separation between different people, teams, or machines, deploy separate Gateways under distinct OS users or on separate hosts.

Roles

Every WebSocket client connecting to the Gateway is assigned one role:

operator: control-plane clients, including the CLI, Control UI, automation tools, and trusted helper processes.
node: capability hosts (macOS, iOS, Android, headless) that expose commands via node.invoke.

Operator RPC methods demand the operator role; methods originating from nodes demand the node role.

Scope levels

Scope	Meaning
`operator.read`	Non-mutating calls: read-only status, lists, catalog, logs, session reads, and similar operations.
`operator.write`	Mutating operator actions: sending messages, invoking tools, updating talk or voice settings, relaying node commands. Also satisfies `operator.read`.
`operator.admin`	Administrative access. Satisfies every `operator.*` scope. Required for configuration changes, updates, native hooks, reserved namespaces, and high-risk approvals.
`operator.pairing`	Managing device and node pairing: list, approve, reject, remove, rotate, and revoke.
`operator.approvals`	APIs for exec and plugin approvals.
`operator.questions`	Listing, reading, answering, and resolving interactive questions.
`operator.talk.secrets`	Reading Talk configuration including secrets.

Unknown future operator.* scopes require an exact match unless the caller already holds operator.admin.

Method scope is only the first gate

Each Gateway RPC is assigned a least-privilege method scope that determines whether a request reaches its handler. Methods that are params-aware derive that scope before dispatch, so authorization failures return a single canonical structured response:

agent needs operator.write for ordinary turns and operator.admin for /new or /reset session lifecycle commands.
node.invoke needs operator.write for ordinary relay commands and operator.admin for browser.proxy, fs.listDir, and terminal.upload.
talk.config needs operator.read; includeSecrets: true also needs operator.talk.secrets.

Some handlers then apply more restrictive checks based on the specific item being approved or mutated:

device.pair.approve is accessible with operator.pairing, but approving an operator device can only create or keep scopes the caller already holds.
node.pair.approve is accessible with operator.pairing, then derives additional approval scopes from the pending node's declared command list.
chat.send is a write-scoped method, but the /config set and /config unset chat commands require operator.admin on top of that, regardless of the caller's chat-send scope.

This allows lower-scope operators to perform low-risk pairing actions without making all pairing approvals admin-only.

Session mutation RPCs are authorized based on their negotiated operator scopes, independent of the connecting client's client.id or client.mode. Client identity can still affect connection and device-auth policy, but it neither grants nor removes session mutation authority.

Device pairing approvals

Device pairing records serve as the durable source for approved roles and scopes. An already-paired device does not silently gain broader access: a reconnect that requests a broader role or broader scopes creates a new pending upgrade request.

Approving a device request:

Operator scope approval is not required when a request carries no operator role.
When a request targets a non-operator device role like node, it demands operator.admin, even though device.pair.approve by itself only requires operator.pairing.
For requests involving operator.read, operator.write, operator.approvals, operator.questions, operator.pairing, or operator.talk.secrets, the caller must already possess that scope or have operator.admin.
A request for operator.admin needs operator.admin.
If a repair request has no explicit scopes, it may inherit the scopes from the existing operator token; when that token is admin-scoped, approval still requires operator.admin.

Non-admin sessions using shared-secret or trusted-proxy authentication can only approve operator-device requests that fall within their own declared operator scopes. Approving non-operator roles is restricted to admin-only, even if those sessions can otherwise use operator.pairing.

For paired-device token sessions, management is self-scoped unless the caller holds operator.admin: a non-admin caller can only view its own pairing entries and can approve, reject, rotate, revoke, or remove only its own device entry.

Node pairing approvals

Legacy node.pair.* methods rely on a separate node pairing store owned by the Gateway. WS nodes instead use device pairing (role: node), though the same approval vocabulary applies. Refer to Gateway pairing for how the two stores relate.

node.pair.approve derives additional required scopes from the pending request's command list:

Declared commands	Required scopes
none	`operator.pairing`
ordinary node commands	`operator.pairing` + `operator.write`
`system.run`, `system.run.prepare`, `system.which`, `browser.proxy`, `fs.listDir`, or `system.execApprovals.get/set`	`operator.pairing` + `operator.admin`

Approving a node declaration does not enable commands that are gated by a separate runtime allowlist. For example, approving a node that declares computer.act requires pairing plus write scope, but only records the surface. An administrator or owner must still arm computer.act. While it remains armed, invoking it through node.invoke requires write scope, but not admin scope for each action.

Node pairing establishes identity and trust; it does not replace a node's own system.run exec approval policy.

Shared-secret auth

Shared gateway token/password authentication is treated as trusted operator access for that Gateway. OpenAI-compatible HTTP surfaces, /tools/invoke, and HTTP session-history endpoints restore the full default operator scope set for shared-secret bearer auth, even if a caller sends narrower declared scopes.

Identity-bearing modes, such as trusted proxy auth or private-ingress none, can still honor explicit declared scopes. Use separate Gateways for real trust boundary separation.