The agent that isn't installed

Connector controls remote Linux hosts without deploying anything to them. The four Python helpers are compiled into the client binary as Qt resources, base64-encoded at call time, and piped through an SSH heredoc into a six-line bootstrap that writes them to ~/.cache/connector-host-runtime/ and executes them. There is no package, no daemon to install, no version to keep in sync — the helper on the host is always exactly the helper in the client you are running.

   1CONNECTOR_HOSTCTL_ACTION='state' CONNECTOR_HOSTCTL_ARGS_B64='W10=' \
   2CONNECTOR_HOSTCTL_SCRIPT_B64='…' CONNECTOR_MICHOST_SCRIPT_B64='…' \
   3CONNECTOR_MIC_PORT='48200' python3 - <<'PY'
   4import base64, json, os, pathlib, subprocess, sys
   5runtime_dir = pathlib.Path.home() / ".cache" / "connector-host-runtime"
   6runtime_dir.mkdir(parents=True, exist_ok=True)
   7script_path = runtime_dir / "linux-hostctl.py"
   8script_path.write_bytes(base64.b64decode(os.environ["CONNECTOR_HOSTCTL_SCRIPT_B64"]))
   9args = json.loads(base64.b64decode(os.environ.get("CONNECTOR_HOSTCTL_ARGS_B64", "W10=")).decode("utf-8"))
  10completed = subprocess.run([sys.executable, str(script_path), os.environ["CONNECTOR_HOSTCTL_ACTION"], *args], check=False)
  11raise SystemExit(completed.returncode)
  12PY

hostctl start is not a wrapper around systemctl start. It repairs the unit first, then starts it, then verifies, then falls back to a direct spawn if systemd could not produce a responding runtime.

ian@linux-host:~$ python3 ~/.cache/connector-host-runtime/linux-hostctl.py state
{
  "ok": true,
  "command": "state",
  "session_env": {
    "DISPLAY": ":1",
    "XDG_SESSION_TYPE": "x11",
    "XDG_CURRENT_DESKTOP": "ubuntu:GNOME",
    "XDG_RUNTIME_DIR": "/run/user/1000",
    "DBUS_SESSION_BUS_ADDRESS": "unix:path=/run/user/1000/bus",
    "XAUTHORITY": "/run/user/1000/.mutter-Xwaylandauth.XXXXXX"
  },
  "environment_ready": true,
  "unit_file_state": "enabled",
  "active_state": "active",
  "sub_state": "running",
  "main_pid": 4471,
  "process_count": 1,
  "duplicate_processes": false,
  "runtime_responding": true,
  "admin_responding": true,
  "http_port": 47989,
  "admin_port": 47990,
  "mic_port": 48200,
  "mic_active_state": "active",
  "mic_virtual_source_ready": true,
  "mic_ready": true,
  "mic_default_source": "connector_virtual_mic",
  "mic_default_source_is_connector": true,
  "pipewire_pulse_active_state": "active",
  "pactl_available": true,
  "pactl_usable": true,
  "wpctl_available": true,
  "pw_cli_available": true
}

admin_port is not a separate constant — it is read_config_port() + 1, where read_config_port() parses port out of the Sunshine configuration file and defaults to 47989.

Pressing a display button in the session overlay does not change what the client requests — it changes what the host captures. Connector treats the host as authoritative and refuses to fake a switch it could not confirm.

Streaming a host's physical desktop means taking it over: whoever is sitting at that machine sees your mouse. The workspace helper builds a second, headless desktop sized to your client, runs its own Sunshine against it, and leaves the physical session untouched. connector-x11-workspace.py apply --runtime-dir <dir> is the entry point; update re-applies a changed display selection and restore tears everything back down.

"Client-matched virtual display active. Use DISCONNECT to end the session."

The controls you need most — disconnect, switch monitor — are hardest to reach while a stream has your pointer captured. Connector's answer is to draw the control bar on the host, inside the picture you are already looking at. It is a GTK 3 window that talks to the client through two files in the runtime directory.

Fixed controls

• LOCATE — warps the pointer onto the overlay and re-runs the sequence at 120 ms, 360 ms and 820 ms, because compositors move windows after they are mapped.
• HIDE — collapses the bar without killing the process.
• DISCONNECT — writes the disconnect command.
• One button per display, labelled by slot, with the active one styled overlay-display.active.

The overlay also carries a drag handle, a pointer guard that keeps the cursor on the current display, and a pid file it cleans up on exit. Its title defaults to "Connector controls" with the subtitle "IN-STREAM".

Moonlight streams audio from host to client. It does not stream a microphone the other way. Connector adds a small, fully specified one-way UDP protocol to close that gap on Linux hosts.