WebSocket API

All communication happens over WebSocket at ws://agent:<port>/ws

Primary Protocol HTTP endpoints are deprecated

Message Format

{
  "id": "unique-message-id",
  "type": "message_type",
  "payload": { ... },
  "error": { "code": 400, "message": "..." }
}

Authentication

Handshake, pairing, tokens
hub_connected Hub → Agent 
{
  "name": "CapyDeploy Hub",
  "version": "x.y.z",
  "platform": "windows",
  "hubId": "hub-abc123",
  "token": "stored-token-or-empty"
}
pairing_required Agent → Hub 
{
  "code": "123456",
  "expiresIn": 60
}
pair_confirm Hub → Agent 
{ "code": "123456" }
pair_success Agent → Hub 
{ "token": "secure-auth-token..." }
pair_failed Agent → Hub 
{ "reason": "pairing code expired" }

RPC Messages

Request/response operations
ping → pong Keep-alive heartbeat
get_info → info_response Get Agent details and capabilities
get_config → config_response Get agent configuration
get_steam_users → steam_users_response List Steam users on device
list_shortcuts → shortcuts_response List shortcuts for a user
create_shortcut → operation_result Create a Steam shortcut
apply_artwork → artwork_response Apply artwork from URL
send_artwork_image → artwork_image_response Upload artwork image binary
delete_game → operation_result Delete game completely (Agent handles everything)
delete_shortcut → operation_result Delete a shortcut by appID
restart_steam → steam_response Restart Steam client

Telemetry & Monitoring

Console log, game log, hardware telemetry
set_console_log_filter → operation_result Set log level bitmask
set_console_log_enabled → operation_result Enable/disable console log
set_game_log_wrapper → operation_result Enable/disable game log wrapper (Linux)

set_console_log_filter payload

{
  "levelMask": 15  // Default: all except Debug
}

Bitmask values:

1 — Log 2 — Warn 4 — Error 8 — Info 16 — Debug 15 — Default (all except Debug)

set_game_log_wrapper payload

{
  "appId": 123456,
  "enabled": true
}

File Browser

Remote filesystem operations (v1.0.0+)

All file data transfers use TCP data channels with MD5 verification. WebSocket is only used for signaling (metadata + TCP port/token exchange). Requires file_browser capability.

Hub → Agent fs_list

List directory contents.

{ "path": "/home/user/Games", "showHidden": false }
Agent → Hub fs_list_response 
{ "path": "/home/user/Games", "entries": [
  { "name": "game.exe", "path": "/home/user/Games/game.exe", "isDir": false, "size": 1048576, "modTime": 1700000000 }
], "truncated": false }
Hub → Agent fs_mkdir / fs_delete / fs_rename

Create, delete, or rename files and directories. Agent responds with operation_result.

// fs_mkdir
{ "path": "/home/user/Games/NewFolder" }

// fs_delete
{ "path": "/home/user/Games/old_file.txt" }

// fs_rename
{ "oldPath": "/home/user/Games/old.txt", "newPath": "/home/user/Games/new.txt" }
Hub → Agent fs_download

Request a file download. Agent opens a TCP server and responds with port/token.

{ "path": "/home/user/Games/save.dat" }
Agent → Hub fs_download_ready 
{ "path": "/home/user/Games/save.dat", "size": 2048, "tcpPort": 54321, "tcpToken": "a1b2c3..." }

Hub connects to agent_ip:tcpPort, authenticates with token, and receives file data using the standard TCP wire format (same as game uploads but in reverse direction).

Hub → Agent fs_upload

Request to upload a file. Agent opens a TCP server and responds with port/token.

{ "path": "/home/user/Games", "name": "patch.zip", "size": 1048576 }
Agent → Hub fs_upload_ready 
{ "tcpPort": 54322, "tcpToken": "d4e5f6..." }

Hub connects to agent_ip:tcpPort, authenticates, and sends file data using the standard TCP wire format with MD5 checksum verification.

File Upload

Binary chunk transfers

Binary Chunk Format

[4-byte header length][JSON header][binary chunk data]

JSON header:
{
  "id": "msg-id",
  "uploadId": "upload-abc123",
  "filePath": "data/game.pak",
  "offset": 0,
  "checksum": "sha256..."
}
init_upload

Initialize upload session

upload_progress

Real-time progress events

complete_upload

Finalize and create shortcut

cancel_upload

Cancel active upload

Push Events

Real-time notifications from Agent
upload_progress Real-time upload progress (bytes, speed, ETA)
operation_event Operation progress (delete, install, restart)
telemetry_status Telemetry collector state (enabled, interval)
telemetry_data Hardware metrics (CPU, GPU, RAM, battery, fan, power)
console_log_status Console log collector state (enabled, level mask)
console_log_data Batch of console log entries with level/source
game_log_wrapper_status Active game log wrappers (appID → enabled)

operation_event payload

{
  "type": "delete",      // "delete", "install", etc.
  "status": "progress",  // "start", "progress", "complete", "error"
  "gameName": "My Game",
  "progress": 50,
  "message": "Restarting Steam..."
}

telemetry_data payload

{
  "timestamp": 1707500000,
  "cpu": { "usagePercent": 45.2, "tempCelsius": 62, "freqMHz": 3200 },
  "gpu": { "usagePercent": 80, "tempCelsius": 71, "freqMHz": 1800 },
  "memory": { "totalBytes": 16000000000, "availableBytes": 8000000000 },
  "battery": { "capacity": 72, "status": "Discharging" },
  "fan": { "rpm": 3200 }
}

console_log_data payload

{
  "entries": [
    {
      "timestamp": 1707500001,
      "level": "warn",
      "source": "script",
      "text": "Deprecated API call"
    }
  ],
  "dropped": 0
}

Timing Constants

Write Wait 30s
Ping Period 5s
Pong Wait 60s
Request Timeout 30s
Binary Request Timeout 120s
Max Message 50MB
Chunk Size 1MB

Error Codes

400 Bad Request
401 Unauthorized (pairing required)
404 Not Found
406 Connections blocked
409 Hub already connected
500 Internal Server Error
501 Not Implemented