Operator scopes

Operator scopes gate what a Gateway client can do after it authenticates. They are a control-plane guardrail inside one trusted Gateway operator domain, not hostile multi-tenant isolation. For strong separation between people, teams, or machines, run separate Gateways under separate OS users or hosts. Related: Security, Gateway protocol, Gateway pairing, Devices CLI.

​

Roles

Every Gateway WebSocket client connects with one role:

• operator: control-plane clients such as CLI, Control UI, automation, and trusted helper processes.
• node: capability hosts (macOS, iOS, Android, headless) that expose commands through node.invoke.

Operator RPC methods require the operator role; node-originated methods require the node role.

​

Scope levels

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 has a least-privilege method scope that decides whether a request reaches its handler. Some handlers then apply stricter checks based on the concrete thing being approved or mutated:

• device.pair.approve is reachable with operator.pairing, but approving an operator device can only mint or preserve scopes the caller already holds.
• node.pair.approve is reachable with operator.pairing, then derives extra 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 lets lower-scope operators perform low-risk pairing actions without making all pairing approval admin-only.

​

Device pairing approvals

Device pairing records are the durable source of approved roles and scopes. An already-paired device does not get broader access silently: a reconnect that asks for a broader role or broader scopes creates a new pending upgrade request. Approving a device request:

• A request with no operator role does not need operator scope approval.
• A request for a non-operator device role (for example node) requires operator.admin, even though device.pair.approve itself only needs operator.pairing.
• A request for operator.read, operator.write, operator.approvals, operator.pairing, or operator.talk.secrets requires the caller to already hold that scope, or operator.admin.
• A request for operator.admin requires operator.admin.
• A repair request with no explicit scopes can inherit the existing operator token’s scopes; if that token is admin-scoped, approval still requires operator.admin.

Non-admin shared-secret and trusted-proxy sessions can only approve operator-device requests within their own declared operator scopes; approving non-operator roles is admin-only even when those sessions can otherwise use operator.pairing. For paired-device token sessions, management is self-scoped unless the caller has operator.admin: a non-admin caller sees only its own pairing entries, and can approve, reject, rotate, revoke, or remove only its own device entry.

​

Node pairing approvals

Legacy node.pair.* methods use a separate Gateway-owned node pairing store. WS nodes use device pairing (role: node) instead, but the same approval vocabulary applies. See Gateway pairing for how the two stores relate. node.pair.approve derives extra required scopes from the pending request’s command list: 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 auth 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.