Permissions & Scopes

Every command a node can execute maps to a permission scope. The Gateway checks scopes before dispatching, so a node without input.control can be asked to click all day and the command never reaches the machine.

Scopes are configured per device, in the Dashboard at Devices → (device) → Settings → Permission scopes.

The scope catalogue

activity.read is one scope doing two jobs. It gates reading the history and changing how it is recorded, because a privacy control the user cannot reach is not a control. In practice that means the node must hold activity.read before the Dashboard's activity settings panel or its timeline work at all: without the scope, neither can read the device's recorder state, and neither can change it.

Four further scope names, browser.control, camera.capture, location.read, and node.ping, are recognised by the permission gate but unimplemented. No command type resolves to them, so no command can ever be authorised by one. Granting one changes nothing, and revoking one protects nothing. They are names reserved for work that has not shipped, not features waiting to be switched on.

What a new node can do

Approving a device grants the eight scopes above marked Granted. Between them they cover looking at the screen, driving input, arranging windows and apps, the clipboard, machine info, notifications, and presenting a Canvas, which is enough to operate a GUI.

What is deliberately not granted is everything that reaches past the screen:

• system.execute. Arbitrary shell access, the single most dangerous thing a node can do.
• filesystem.access. Reading and writing the user's files.
• activity.read. Reading a record of the user's working day, and deciding whether one is kept at all.
• voice.runtime. Speaking aloud in a room you may not be in.

Each of those is a separate, deliberate decision. That is the whole design: the default grant makes a node useful, and every escalation past it is something a person chose.

The wildcard scope

node.command grants everything: every scope, every command. It is a scope name, not a tool; the tool that once bore this name was removed. See the three agent tools.

Reasonable uses:

• A trusted personal device where you are the sole user and operator.
• Temporary troubleshooting: grant, debug, revoke.
• A VM or container dedicated to automation.

On any machine another person can reach, grant specific scopes instead.

Why system.execute is treated differently

Shell access can exfiltrate data, modify files, install software, or pivot to other machines on the network. Holding the scope is necessary but not sufficient: it is rated Critical, so it also requires a per-call approval that no run-level consent can pre-cover, it raises a prompt on the node's own screen showing the exact command, and the node refuses a built-in denylist of catastrophic patterns outright.

If you do not want shell access, do not grant the scope. The scope gate is the cheapest layer and keeps your approval queue clear. The mechanics are in Gates, Limits & Audit.

Granting scopes in the Dashboard

The panel groups the scopes for readability, one checkbox per scope: Screen, Input, Applications, Windows, Clipboard, System (info and shell as separate checkboxes), Files, Notifications, Voice, Browser, Canvas, and Full Access. The panel does not show a risk rating; the per-command risk is in Commands & Actions, and that is the thing to read before you tick a box.

Changing and revoking

Scope changes take effect immediately. The node receives a refresh over its existing connection and updates its policy, with no restart.

Revoking a scope does not cancel in-flight commands. A capture that started two seconds before screen.capture was revoked still completes; the next one is refused.

For the node as a whole, a device is in one of three pairing states — Pending, Approved, Revoked — and there are three levers:

• Clear its scopes. Save an empty scope set and every command is refused at the Gateway while the device stays paired and connected. The right first move when something looks off, and the fastest thing to undo.
• Revoke. The device moves to Revoked and its credential is destroyed. Commands are refused from that moment, and the node cannot authenticate again, so it cannot come back without being paired afresh. Audit history is kept.
• Rotate the token. sophon nodes rotate-token issues a fresh credential when you want continuity rather than a revocation.

There is no pause state and no delete. A device you are finished with is revoked, and its audit history survives the revocation.

Multi-node patterns

Each node carries its own scopes. A common shape:

• An office desktop on the default eight, which is enough to drive GUI apps.
• A lab machine on the wildcard, because you are its only user.
• A home server on system.info and notify.send alone, because you only want status out of it.

Name nodes clearly. An agent routing work to the wrong machine is a configuration smell, and a run is pinned to whichever node it resolved first.

Auditing

Every dispatch is recorded with its node, command type, outcome, and the scope that authorised it, or the gate that refused it. Dashboard → Admin → Audit filters on node activity, and the full outcome list is in Gates, Limits & Audit.

Where to go next

• Gates, Limits & Audit — the four checks, the rate limits, and every audit outcome
• Commands & Actions — every command type and what it needs
• File Access — what filesystem.access actually permits
• Approval Gates — how risk tiers decide what gets asked