Gates, Limits & Audit
The four checks every node command passes, the per-command rate limits, the on-device consent prompt, and what the audit log records.
Every command that reaches a node crosses four gates in a fixed order. The first one that says no ends it, and each refusal is recorded distinctly, so "it didn't run" is always answerable with which gate stopped it.
The four gates
| Order | Gate | Checks | Outcome on refusal |
|---|---|---|---|
| 1 | Handler | The command type exists at all | rejected.unknown |
| 2 | Permission scope | The node holds the scope this command needs | rejected.permission |
| 3 | Rate limiter | This command type is not being called too fast | rejected.rate_limit |
| 4 | Consent | The person at the machine approved it | rejected.consent, or rejected.consent_pending for input while a dialog is open |
The scope check happens twice on purpose: once on the Gateway before dispatch, and again on the node itself. A node does not assume the server upstream is honest.
Rate limits
Each command type carries its own burst allowance and refill rate, applied on the node. They exist to bound a runaway loop, not to shape normal use: ordinary automation never touches them.
| Command type | Burst | Refill |
|---|---|---|
screen.capture, screen.region, screen.queryElements | 10 | 5 per second |
input.mouse.move | 60 | 60 per second |
input.mouse.click, input.mouse.scroll, input.keyboard.press | 20 | 20 per second |
input.keyboard.type, input.keyboard.hotkey | 10 | 10 per second |
app.launch, app.close | 4 | 1 per second |
app.focus, clipboard.read, clipboard.write | 10 | 5 per second |
notify.show | 5 | 1 per second |
system.execute | 3 | 0.5 per second |
everything else, including the activity.* and filesystem.* commands | 30 | 15 per second |
A refusal here is recorded, not silent. A node being hammered shows up in the audit log rather than merely going quiet.
This is not the same thing as the Gateway's HTTP rate limiting, which bounds API callers rather than desktop commands. See Rate Limiting for that.
The on-device consent prompt
Some commands raise a native dialog on the node's own screen before they run, a final local line of defence that holds even if everything upstream is compromised. Since v2.2.0 the dialog's title names the action (for example "Sophon Node: Run a shell command") and its text shows the full detail: the command line, every app argument, the file path and content, and the whole typed text, up to 4,000 characters. Control, bidi-override and zero-width characters are shown as \uXXXX escapes, so text cannot hide part of what is about to run.
It times out after 15 seconds and fails closed: no answer means refused.
Since v2.2.0 the dialog is also hardened:
- The default answer is No. The Windows dialog's default button is No, and on Linux the default is Reject, so pressing Enter refuses.
- No PowerShell injection on Windows. The dialog and
notify.shownotifications run a fixed PowerShell script and receive their text on standard input, so quotes,$(…)and backticks in a command are shown as typed and never run. On Linux the dialog no longer renders markup. - Stop closes it. A Stop sent while the dialog is open closes it, on macOS too, and the command is recorded
cancelledwithout running. When the agent stops waiting for a node command, the Gateway cancels the command on a connected device the same way. - Input waits for it. While a dialog is open, mouse and keyboard commands are refused (
rejected.consent_pending), so an agent cannot click its own Approve, and Remote view cannot answer the dialog either. - A dialog that cannot open says so. No desktop session, a missing component or an osascript error on macOS refuses with "Consent prompt not available on this platform" rather than reading as a rejection. Either way the command does not run.
It also fails closed when the prompt cannot be shown at all. A node with no interactive desktop session cannot obtain consent, so it cannot run consent-required commands. That is one of the reasons a node is meant to run as a user-level service, not a system one.
By default this covers system.execute and canvas.present. The list is configurable per device through consentRequiredCommands in the config file; adding a command type to it makes that command ask locally every time.
Since v2.2.0 the device's owner can also manage the list from the Dashboard, and switch the dialog off for 1 hour, 8 hours, 24 hours, 7 days or until turned back on. Actions on the list then run without the dialog and are audited skipped.consent. A person at the machine can run sophon-node lock so that Sophon cannot do this, and an operator can forbid it for the whole Gateway with Sophon:Nodes:AllowConfirmationsOff. See Device Settings & Confirmations.
Since v2.2.0, on macOS and Linux a command that is stopped or reaches its timeout ends its helper process and everything that process started, and waits for it to exit before reporting, as Windows already did for shell commands. A script that should outlive its command must detach itself, for example with nohup … &.
Plan-level consent
Approving a desktop run can also cover further actions at that risk level, on that machine, for the rest of the run, so a five-step batch does not produce five prompts.
It is bounded on every axis:
- Interactive chat turns only. A workflow, a scheduled or cron run, a heartbeat turn, a webhook turn and an MCP call are never covered: each one asks again on every single call. Nobody is watching those runs, so nothing is carried through them.
- Thirty minutes, then it lapses.
- One conversation. It does not leak into another.
- Held in memory, never written to disk. A Gateway restart clears it.
- Never covers Critical. A shell command asks again, every time, no matter what was approved before.
- Dropped when the session's work is cancelled, which is what Stop in the Dashboard chat does.
An automatic approval never establishes it. Only a person can, and the prompt only promises run-wide coverage where that coverage is real: a caller that will be asked again every time is not told otherwise.
Approvals fire once, before execution
An approval is raised before the tool runs, not partway through it, so a refusal means nothing happened rather than something half-happened. It is raised once per call, and it is delivered to the channel the conversation is actually in — Telegram, WhatsApp, and the rest — rather than only to a Dashboard nobody has open.
At the shipped default threshold, a node shell command raises two prompts: the general one for the tool call, then the Critical one carrying the exact command line about to run. It is redundant rather than unsafe, and it fails closed in both places. Collapsing the two is a roadmap item, not current behaviour.
The shell denylist
Beyond scope, approval, and consent, the node refuses a built-in list of catastrophic command patterns outright. It covers recursive deletes of a filesystem root, disk formatting, shutdown and reboot, piping a download straight into a shell, and a few others in the same family.
The denylist is a backstop, not the security model. It catches the obviously destructive; it is not a sandbox and cannot be relied on to make shell access safe. If you need shell access to be safe, do not grant it.
Note also that a shell command must arrive as one complete string. Separate arguments are refused, precisely so that approval, denylist, audit, and execution are all reviewing the same text. An argument list that gets recombined later is a place for the reviewed command and the executed command to drift apart.
Audit outcomes
Every dispatch ends in exactly one of these outcomes:
| Outcome | Meaning |
|---|---|
rejected.unknown | No handler for that command type |
rejected.permission | The node does not hold the required scope |
rejected.rate_limit | Too many of that command type, too fast |
rejected.consent | Refused at the machine, the prompt timed out, or it could not be shown |
rejected.consent_pending | Since v2.2.0. A mouse or keyboard command arrived while a confirmation dialog was open |
completed | Ran and returned a result |
failed | Ran and returned an error |
cancelled | Stopped in flight, by a person, a cancelled turn, or the agent's timeout. "Cancelled while waiting for confirmation on the device." when its dialog was open |
error | The node could not process the command at all |
Since v2.2.0 the node also records the confirmation decisions themselves, next to those outcomes. Audit queries that count rows per command see one more for a command approved in the dialog:
| Record | Meaning |
|---|---|
approved.consent | The person allowed the action in the dialog. Its duration is the time the dialog was open. rejected.consent rows now carry that time too |
skipped.consent | Confirmations were off from Sophon, so the action ran without the dialog |
consent.rearmed | An off period ended, or the settings from Sophon were missing or unreadable, and the dialog asks again |
policy.locked, policy.unlocked | Someone ran sophon-node lock or unlock on the machine |
settings.applied, settings.refused | The node applied settings from Sophon, or refused some, with the reason |
The Confirmations panel in the Dashboard lists a device's last 20 of these for its owner or an admin. On the Gateway, nodes.settings.update, nodes.settings.refused and nodes.rename rows record who changed a device's settings.
Each carries the node, the command type, the scope that authorised it, timing, and the initiating user. They stream into the Gateway's audit log and appear inline in the Dashboard chat and on the Devices page.
The node also reports per-command latency and per-gate refusal counts with its heartbeat, so a device refusing everything is visible without opening the log. If it is offline when something happens, audit events are buffered locally and delivered when it reconnects.
Where to go next
- Permissions & Scopes — which scopes exist and which eight you start with
- Control Runs — how one approval covers a whole batch
- Approval Gates — the risk tiers behind these decisions
- Audit — where node events land for compliance
Device Settings & ConfirmationsNEW
Rename a node, choose its folders, and switch its on-device confirmations off for a while from the Dashboard, with the local lock and the host kill switch that bound it.
Platform Support & Limits
What each operating system supports today, what this release does not include, and what is planned.