The socket is the product

Connector's UI, its CLI, its daemon and its MCP bridge are four consumers of the same thing: a local Unix domain socket that accepts one JSON request per connection and returns one length-prefixed JSON response. There is no HTTP server, no authentication token, no bearer header. The security model is filesystem permissions and the assumption — stated plainly in the README — that the caller is the same human who started the app.

The protocol is deliberately small enough to reimplement in an afternoon, and it has in fact been implemented twice in this repository: once in C++ (shared/src/connectorcontrolclient.cpp) and once in Python (scripts/connector_control.py). Both are about a hundred lines.

Both servers dispatch on a flat method string. The daemon implements a strict subset and answers the rest with a single, informative refusal. The table below is the complete difference.

The CLI is a thin, explicit mapping from verbs to methods. Its usage block is the closest thing the project has to a protocol specification, and every flag below is parsed by hand in main() — there is no QCommandLineParser here.

  16Usage:
  17  connectorctl state
  18  connectorctl rpc <method> [json-params]
  19  connectorctl actions global
  20  connectorctl actions device <device-id>
  21  connectorctl devices list
  22  connectorctl devices get <device-id>
  23  connectorctl devices select <device-id>
  24  connectorctl devices connect <device-id> [app-name]
  25  connectorctl devices pair <device-id>
  26  connectorctl devices rename <device-id> <name>
  27  connectorctl devices ssh-profile <device-id> [--mode auto|ssh|tailscale] [--user <user>]
  28  connectorctl host state
  29  connectorctl host set-enabled <true|false>
  30  connectorctl host set-credentials <username> <password>
  31  connectorctl ui tree [--include-hidden] [--include-internal]
  32  connectorctl ui screenshot [--page <page>] [--control <id>] [--out <path>] [--inline]
  33  connectorctl ui activate <id>
  34  connectorctl ui set <id> <value>
  35  connectorctl ssh exec <device-id> [--user <user>] [--mode auto|ssh|tailscale] -- <command...>

$ build/connector-app/connectorctl rpc ssh.prepare \
    '{"device_id":"nZ55Q5PqHN11CNTRL","command":["systemctl","--user","is-active","sunshine"],"mode":"tailscale"}'
{
    "args": [
        "ssh",
        "[email protected]",
        "--",
        "sh",
        "-lc",
        "systemctl --user is-active sunshine"
    ],
    "program": "/Applications/Tailscale.app/Contents/MacOS/Tailscale",
    "timeout_ms": 10000
}

$ build/connector-app/connectorctl ssh exec nZ55Q5PqHN11CNTRL --mode auto -- whoami
{
    "args": [
        "-o", "BatchMode=yes",
        "-o", "NumberOfPasswordPrompts=0",
        "-o", "KbdInteractiveAuthentication=no",
        "-o", "PasswordAuthentication=no",
        "-o", "PreferredAuthentications=publickey",
        "-o", "ConnectTimeout=5",
        "-o", "StrictHostKeyChecking=accept-new",
        "-o", "UseKeychain=no",
        "-o", "UserKnownHostsFile=/Users/ian/Library/Application Support/Connector/known_hosts",
        "[email protected]",
        "whoami"
    ],
    "exit_code": 0,
    "finished": true,
    "program": "/usr/bin/ssh",
    "started": true,
    "stderr": "",
    "stdout": "ian\n",
    "timed_out": false
}

ssh.prepare exists so a caller can see the exact command before authorising it. Both methods return the same program and args pair; only one of them runs it. That separation is what makes the MCP tool connector_prepare_ssh_command safe to expose to an agent that is still deciding.

Nothing calls connectord directly. Everything goes through ensure-connectord.py, which is considerably more careful than a pgrep would be about deciding whether a daemon is already there.

Flags

When the desktop app is the one listening, the socket also exposes the live QML object tree. Nodes are filtered by shouldExposeUiObject(), which honours --include-hidden and --include-internal, and identified by the automationId property that QML components set on themselves.

$ build/connector-app/connectorctl ui activate nav-this-computer
{
    "activated": true,
    "id": "nav-this-computer"
}

$ build/connector-app/connectorctl ui screenshot --page page-this-computer --out /tmp/shot.png
{
    "height": 1880,
    "path": "/tmp/shot.png",
    "width": 3000
}

$ build/connector-app/connectorctl ui set settings-absolute-mouse false
{
    "id": "settings-absolute-mouse",
    "value": false
}

$ scripts/connectorctl-daemon.sh ui activate nav-this-computer
ui.activate requires the Connector desktop app or streaming session process.
The headless daemon only exposes device discovery, settings, and SSH control right now.

This is what the connector_automation ctest suite exercises: it launches Connector offscreen, waits for the socket, validates state and action discovery, exports the tree, captures screenshots, checks connectorctl, and smoke-tests the MCP wrapper's import path — all through this one interface.

Every control the human can press has a stable string id, and every one of those ids is reachable from a shell. The GUI is not a special case; it is one more client of the socket.