Sophon NodeNEW

Sophon Node is a background service that turns a Windows, macOS, or Linux machine into an endpoint your agent can operate. It pairs with your Gateway, holds one outbound connection, and executes commands locally: capture the screen, move the mouse, type, launch apps, manage windows, read and write the clipboard and files, and, when you allow it, run a shell command.

The reasoning happens on the Gateway. The node executes; it never decides what to do. That separation is what keeps the security model legible: everything the node will do arrives as a named command, and every named command passes the same gates.

Work does not arrive one command at a time. An agent sends a Control Run: an ordered batch of actions, approved once, pinned to one machine, ending with a screenshot. The model actually sees that screenshot, and can check its own work against it, on Claude models reached through the Anthropic API or a connected Claude subscription. On other provider paths — OpenAI-compatible, Gemini, Bedrock, Copilot — the run comes back as text alone.

What a node is for

• Automating a desktop app that has no API. A legacy accounting tool, a vendor portal that insists on browser plugins, a spreadsheet macro.
• Flows that need a real, logged-in session. Clicking through a site that only works with saved state.
• Remote work. You are away from your desk and the agent can finish something on your office machine.
• Multi-machine setups. One Gateway coordinating several nodes across home, office, and lab.
• Spoken output on a machine you are not sitting at. A node can read a result aloud through the operating system's own speech synthesiser. It cannot listen: there is no microphone capture and no wake word on a node, and a voice turn reaches a smaller tool set than a chat turn. Driving a desktop by speaking to it is not something this release does.

Don't use a node when:

• A web API exists. Use a connection or an MCP server instead. APIs are faster and far more reliable than driving a GUI.
• You want unattended server automation. Nodes are built for user desktops with a live session, not headless servers.

The three agent tools

Three tools reach a node. They do different jobs and are documented separately.

Actions and command types

Two vocabularies appear throughout these pages, and they are not interchangeable.

Actions are what an agent names inside a run. Command types are what crosses the wire, what a permission scope gates, and what the audit log records. Some are spelled identically: screen.capture and app.focus are the same on both sides, which is exactly why the ones that differ are worth knowing. Where a page documents parameters, it heads each entry with both.

Architecture

Dashboard / Agent / CLI
        │
        ▼
  Sophon Gateway
  (node hub + node runtime)
        │   SignalR (/hubs/node)
        ▼
  Sophon Node (background service)
        │
   platform automation
   /        |        \
Windows   macOS    Linux

• Standalone binary. The node is a self-contained background service, fully decoupled from the server runtime. Self-contained builds bundle the runtime; the dotnet tool install uses the machine's own.
• Outbound only. The node opens one connection to the Gateway and keeps it. Nothing listens for inbound traffic on the machine, and no port needs opening. If the connection drops it reconnects on its own, backing off and jittering up to a ceiling.
• Scope-gated commands. Every command type maps to a permission scope, checked before dispatch.
• 30-second heartbeat. The Gateway treats a node as offline after two minutes of silence.

Lifecycle

1. Register a node in the Dashboard and collect its pairing credentials.
2. Pair the machine by running sophon-node pair on it. It polls the Gateway until you approve.
3. Approve in the Dashboard. The device starts with eight scopes; the rest you grant deliberately.
4. Start it with sophon-node start, or --service to run without a console.
5. Drive it: the agent sends a remote.control run. The Gateway checks scopes, then dispatches.
6. Unpair when you are done. sophon-node unpair clears local state, and the Dashboard can revoke the token.

Security model

Four layers, each documented where it belongs:

1. Pairing approval. A node can do nothing until someone approves its pairing. Unpaired nodes are rejected at the connection layer.
2. Permission scopes. Per-device, checked on the Gateway before a command is dispatched. See Permissions & Scopes.
3. The dispatch gates. On the node itself, every command passes four checks in a fixed order. See Gates, Limits & Audit.
4. On-device consent. The riskiest commands raise a prompt on the node's own screen, so the person at the keyboard has the last word even if everything upstream is compromised.

Ownership is enforced where work is queued, not only at the HTTP edge: asking for a machine that is not yours returns the same answer as asking for one that does not exist.

Quick start

# On the target machine
sophon-node pair --gateway https://gw.example.com --node-id <ID> --secret <SECRET>
# In the Dashboard: approve the pending node, review its scopes
sophon-node start

The agent can now send a run:

remote.control({
  actions: [
    { action: "app.focus",      params: { name: "chrome" } },
    { action: "mouse.click",    params: { x: 640, y: 480, button: "left" } },
    { action: "keyboard.type",  params: { text: "Hello world" } }
  ],
  observe: "screenshot"
})

Where to go next

• Install & Pair a Node — the setup walkthrough, the config file, and the CLI
• Control Runs — how a batch executes, and what one approval covers
• Commands & Actions — every command type and every action
• Permissions & Scopes — what each scope grants, and which eight you start with
• Platform Support & Limits — what each OS supports, and what has not shipped