Permissions & Scopes

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

Dashboard layout

The Dashboard groups scopes for easier configuration. Checkboxes expand to show individual commands:

• Screen — screen capture + region capture
• 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)
• Files — filesystem read/write
• Notifications — OS notifications
• Voice — voice runtime
• Browser — browser automation
• 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 if you grant system.execute at the scope level, the command is still Critical-risk at the approval layer. Every invocation fires an approval request. There's no "trust this tool" override.

Quiet hours apply: during configured quiet hours, system.execute requests are auto-rejected rather than queued.

If you don't want shell access at all, don't grant system.execute in the first place. The scope gate is faster than the approval gate and avoids filling your approval queue.

Filesystem scope

filesystem.access is also powerful — it lets the Node read/write files anywhere in the user's home directory. It's High-risk (not Critical) because file operations are generally reversible and less likely to trigger arbitrary code execution.

Still, apply least privilege:

• Grant it only if your agent actually needs to manipulate files (downloading reports, saving extracted data, etc.).
• Specific commands (filesystem.read, filesystem.write, filesystem.list, filesystem.delete) all gate at their own risk levels.

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 denied if 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.info and notify.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 — the 23 commands and what each needs
• Approval Gates — how system.execute and other Critical commands gate
• Install & Pair a Node — the setup walkthrough