Skip to the content.

VxDesk — Remote Services contract (host ↔ agents)

VxDesk can act as a hub: remote machines connect in (or poll), receive workflow-run commands, execute them locally, and report all activity back. Three transports:

Transport Endpoint Client Notes
WebSocket ws(s)://host:8765/ws/remote full agent push, realtime, wss when TLS configured
TCP host:8766 (configurable) full agent / tiny clients JSON-lines, length-free (one JSON object per line)
Edge poll http(s)://host:8765/api/edge/* legacy edge client plain HTTP+JSON, stdlib-only, XP-Embedded-friendly

Security model: remote access is OFF by default. Enabling it requires a bind address choice (127.0.0.1 default) and generates a hub token. Every agent authenticates with token (hello message / X-VxDesk-Token header / ?token= query — all accepted, because the oldest clients can barely set headers). Tokens are per-agent, revocable. TLS is optional: user supplies cert/key paths in settings (scripts/make_dev_cert.ps1 generates a dev self-signed pair); when set, uvicorn serves HTTPS+WSS.

Message protocol (ws + tcp, one JSON object per message/line)

Agent → hub:

{"type": "hello", "agent_id": "mach-01", "name": "Shop floor PC", "token": "…",
 "caps": {"os": "windows", "engine": true, "workflows": true}}
{"type": "event", "kind": "log|status|run_started|run_finished", "message": "…", "run_id": "…", "ts": 1234.5}
{"type": "result", "command_id": "cmd_…", "ok": true, "output": {…}, "error": null}
{"type": "pong", "ts": 1234.5}

Hub → agent:

{"type": "welcome", "ok": true, "error": null}
{"type": "command", "command_id": "cmd_…", "command": "run_workflow",
 "workflow_id": "wf_…", "workflow": {…full graph JSON…}, "dry_run": false}
{"type": "ping", "ts": 1234.5}

Rules: first agent message MUST be hello; bad token → {"type":"welcome","ok":false,"error":"…"} + close. workflow is the FULL graph (self-contained — agents never call back for it).

Edge polling API (legacy-friendly: HTTP/1.0-safe, no chunked requirements)

Edge v1 command types: run_workflow (full agents) and shell ({command: "…"} — the legacy edge client executes it and reports stdout/stderr/exit code). Legacy client MUST refuse run_workflow (no engine) and report ok:false, error:"unsupported".

Hub management REST (used by the Remote page)

Full agent (python -m vxdesk.agent)

Flags: --server ws://host:8765 (or tcp://host:8766), --token, --agent-id, --name, --dry-run-default. Reconnect with backoff (1s→30s cap). Executes run_workflow with the embedded engine (workflow JSON from the command), streams run_started/log/run_finished events + final result. Windows-service friendly: no console interaction, logs to file. scripts/install-agent-service.ps1 (NSSM-free: Task Scheduler at boot, powershell -WindowStyle Hidden).

Legacy edge client (edge/vxdesk_edge.py)

ONE file, stdlib only, Python 2.7 AND 3.4+ compatible (no f-strings, no pathlib, urllib2/urllib shim). INI config (server, agent_id, token, interval, insecure_tls). Poll loop with backoff on failure. Executes only shell commands; reports events/results each cycle. --once flag (single cycle, for testing/schedulers). XP note in its docstring: old TLS — prefer plain HTTP on a trusted LAN or stunnel.

Testing requirements