Permissions & Scopes
Permission scopes configured per-Node — what each grants, the risk level behind each command type, and why system.execute is always gated.
Every command a Sophon Node can execute maps to a permission scope. The Gateway checks scopes before dispatching — so if a Node doesn't have input.control, the agent can call input.mouse.click all day and the Gateway will reject it without ever touching the Node.
Scopes are configured in the Dashboard at Settings → Devices → <node> → Permissions.
Scope reference
| Scope | Commands covered | Risk | Typical use |
|---|---|---|---|
screen.capture | screen.capture, screen.region, screen.monitors, screen.queryElements | Low | Screenshots, monitor info, accessibility tree |
input.control | input.mouse.*, input.keyboard.* | Medium | Click, type, press, scroll, hotkey |
app.manage | app.launch, app.close, app.focus, app.list | Medium | Open/close/focus applications |
window.manage | window.list, window.move, window.minimize, window.maximize | Low | Reposition and resize windows |
clipboard.access | clipboard.read, clipboard.write | Low | Clipboard read/write |
system.info | system.info, system.processes | None | Machine info, process listing |
system.execute | system.execute | Critical | Run shell commands — consent-gated on the device |
notify.send | notify.show | None | Show OS notifications |
canvas.control | canvas.present | Medium | Open an agent Canvas on the Node's screen — consent-gated |
node.command | All commands (wildcard) | Full access | Grants every scope |
A few scopes are reserved for future releases — the scope name exists and can be granted, but no commands are wired up to them yet: filesystem.access, browser.control, voice.runtime, camera.capture, and location.read.
Dashboard layout
The Dashboard groups scopes for easier configuration. Checkboxes expand to show individual commands:
- Screen — capture, region, monitor info, accessibility tree
- Input — mouse and keyboard control
- Applications — launch, close, focus, list
- Windows — list, move, minimize, maximize
- Clipboard — read + write
- System — info / processes (one checkbox) + shell execute (separate checkbox)
- Canvas — present a Canvas on the Node's screen
- Notifications — OS notifications
- Full Access — wildcard
Each group has a risk chip showing the highest-risk command in the group. This is the first thing to glance at when granting scopes.
The "Full Access" wildcard
node.command grants everything — all scopes, all commands. Use it only for:
- Trusted personal devices where you're the sole user and operator.
- Temporary troubleshooting — give, debug, revoke.
- Nodes running inside a dedicated VM or container dedicated to automation.
For any Node where another user has shell access or any Node on a shared machine, grant specific scopes instead.
Why system.execute is always gated
The system.execute scope lets the agent run arbitrary shell commands on the Node's machine. That's maximally powerful and maximally dangerous: shell access can exfiltrate data, modify files, download malware, or pivot to other systems on the network.
Even with the scope granted, system.execute is Critical-risk and passes two extra gates: the Gateway's approval gate and an on-device consent prompt (below). There's no "trust this tool" override, and the Node also enforces a built-in denylist that refuses catastrophic command patterns.
If you don't want shell access at all, don't grant system.execute in the first place. The scope gate is the cheapest layer and avoids filling your approval queue.
On-device consent prompts
Some commands also prompt the person sitting at the Node before they run — a final, local line of defense that holds even if the Gateway-side approval path is bypassed. By default this covers system.execute and canvas.present, and it's configurable through the consentRequiredCommands list in ~/.sophon-node/config.json.
When such a command arrives, the Node shows a native dialog — a Windows toast, a macOS dialog, or a Linux notify-send / zenity prompt — naming the command and, for shell execution, the exact command line. The prompt times out after 15 seconds and fails closed: no response means the command is rejected.
Changing scopes
Scope changes take effect immediately — no Node restart required. The Node receives a scope-refresh event via SignalR and updates its local policy.
Revoking a scope does not cancel in-flight commands. A screen capture that started 2 seconds before screen.capture was revoked will still complete. Subsequent calls fail.
Auditing
Every command execution is logged with:
- Node ID, command, arguments (redacted if sensitive)
- Scope that authorized it (or
deniedif rejected) - User who initiated (via agent chain)
- Duration, exit status, truncated output
Dashboard → Admin → Audit filters on category: node. Enterprise audit streams also cover Node activity.
Revoking a Node
Three levels of severity:
- Pause — temporarily disables command dispatch. The Node stays online but all commands are rejected.
- Revoke token — kills the current token. The Node disconnects immediately and can't reconnect. Reconnection requires re-pairing.
- Delete — removes the Node entry entirely. History is preserved for audit, but the Node is gone from the listing.
Pause is the right first move when something looks off. Revoke + Delete is the right move when you're retiring a machine.
Multi-Node considerations
Each Node has its own scope configuration. It's common to have:
- An Office PC Node with
screen.capture,input.control,app.manage,clipboard.access— enough to drive GUI apps. - A Lab machine Node with
node.command(full access) — you're the sole user and you need everything. - A Home server Node with only
system.infoandnotify.send— you just want it to report status.
Name your Nodes clearly. Agents that route to the wrong Node are a configuration smell.
Where to go next
- Available Commands — every command and what each needs
- Approval Gates — how
system.executeand other Critical commands gate - Install & Pair a Node — the setup walkthrough