Available Commands

Commands are invoked from the agent via the node.command tool, from the Dashboard's Node Console, or from the CLI (sophon node exec). Every command runs inside the Node's platform abstraction — same API surface on Windows, macOS, and Linux with OS-specific implementations under the hood.

Required scopes appear in every section. See Permissions & Scopes for scope configuration.

Screen

screen.capture

Captures the full primary display.

Scope: screen.capture · Risk: Low

Response: { image: "<base64-jpeg>", sizeBytes, format: "jpeg" }

screen.region

Captures a rectangular region.

Scope: screen.capture · Risk: Low

Response: { image, sizeBytes, format, region: { x, y, width, height } }

Mouse

input.mouse.move

Move cursor to absolute coordinates.

Scope: input.control · Risk: Medium

input.mouse.click

Scope: input.control · Risk: Medium

input.mouse.scroll

Scope: input.control · Risk: Medium

Keyboard

input.keyboard.type

Types a string character by character.

Scope: input.control · Risk: Medium

input.keyboard.press

Presses a single named key.

Scope: input.control · Risk: Medium

input.keyboard.hotkey

Modifier combinations.

Scope: input.control · Risk: Medium

Applications

app.launch

Launch an application by name or path.

Scope: app.manage · Risk: Medium

Response: { pid: 5678, app: "chrome.exe" }

app.close

Close a running application (graceful — sends WM_CLOSE or equivalent, then kills after 5 s).

Scope: app.manage · Risk: Medium

app.focus

Bring an app's window to the foreground.

Scope: app.manage · Risk: Medium

app.list

List apps with visible windows.

Scope: app.manage · Risk: Medium

Response: { count: 5, apps: [ { name, pid, windowTitle } ] }

Windows

window.list

All visible windows with geometry.

Scope: window.manage · Risk: Low

Response:

{
  "count": 3,
  "windows": [
    { "id": "0x00010234", "title": "Untitled - Notepad",
      "x": 100, "y": 100, "width": 800, "height": 600,
      "processName": "notepad.exe" }
  ]
}

window.move

Move and optionally resize.

Scope: window.manage · Risk: Low

window.minimize, window.maximize

Scope: window.manage · Risk: Low

Clipboard

clipboard.read

Scope: clipboard.access · Risk: Low

Response: { text: "...", length: 42 }

clipboard.write

Scope: clipboard.access · Risk: Low

System

system.info

Machine info.

Scope: system.info · Risk: None

Response:

{
  "osDescription": "Microsoft Windows 11.0.26200",
  "machineName": "DESKTOP-ABC",
  "processorCount": 8,
  "totalMemoryMb": 16384,
  "dotnetVersion": ".NET 10.0.0",
  "uptime": 3600,
  "platform": "windows",
  "architecture": "x64"
}

system.processes

All running processes.

Scope: system.info · Risk: None

Response: { count: 42, processes: [ { pid, name, cpuPercent, memoryMb } ] }

system.execute

Run shell command. Always approval-gated regardless of scope config.

Scope: system.execute · Risk: Critical

Runs via platform shell:

• Windows: cmd.exe /c "<command> <args>"
• macOS: /bin/zsh -c "<command> <args>"
• Linux: /bin/bash -c "<command> <args>"

Response: { exitCode, stdout, stderr, durationMs }

Output truncated to 1 MB per stream.

Notifications

notify.show

Show an OS notification.

Scope: notify.send · Risk: None

Implementation:

• Windows: Microsoft.Toolkit.Uwp.Notifications or shell toast
• macOS: osascript -e 'display notification ...'
• Linux: notify-send

Filesystem (High risk)

filesystem.list

Scope: filesystem.access · Risk: High

Response: { entries: [ { name, path, isDirectory, sizeBytes, modifiedUtc } ] }

filesystem.read

Scope: filesystem.access · Risk: High

Response: { content: "<base64 or text>", encoding, sizeBytes }

filesystem.write

Scope: filesystem.access · Risk: High

filesystem.delete

Scope: filesystem.access · Risk: High

Calling conventions

From an agent

node.command({
  nodeId: "office-pc",
  command: "screen.capture",
  params: { quality: 80, maxWidth: 1280 }
})

The agent selects the target Node by ID. For users with multiple Nodes, agents can call node.list first and ask which to use.

From the Dashboard Node Console

Settings → Devices → <node> → Console has a live interactive REPL. Type commands and see results immediately. Useful for debugging scope configuration.

From the CLI

sophon node list
sophon node exec <node-id> screen.capture --quality 80
sophon node exec <node-id> input.mouse.click --x 100 --y 200
sophon node exec <node-id> system.execute --command "echo hello"

Timeouts

Every command has a default 30-second execution timeout. Long-running commands (large screen captures, shell commands) should pass timeoutMs explicitly.

If the Node doesn't respond within the timeout, the Gateway returns { error: "timeout" } but doesn't cancel the in-flight work on the Node. For commands that can't be interrupted cleanly, the side effect may still complete.

Error responses

{
  "ok": false,
  "error": "not_authorized",
  "message": "Node does not have required scope: input.control"
}

Common error codes:

• not_authorized — scope missing
• approval_rejected — approval gate rejected (Critical commands only)
• timeout — command exceeded its execution budget
• node_offline — Node isn't connected to the Gateway
• platform_unsupported — command not available on this OS
• invalid_params — params failed validation
• internal_error — unexpected failure on the Node (check Node logs)

Where to go next

• Install & Pair a Node
• Permissions & Scopes — scopes required per command
• Running as a Service — keep the Node online