Host-uri

Relay-ul care lasă un telefon să ruleze o operație pe desktop-ul tău: stream de prezență, exec și rezultat.

Un host e un dispozitiv care ține deschis GET /v1/hosts/stream. Alt dispozitiv trimite un exec; gateway-ul îl retransmite peste acel stream și blochează până când host-ul trimite rezultatul sau expiră timeout-ul. Prezența expiră la 45 s după ultimul heartbeat. Relay-ul e best-effort și nu face parte din specificația publică a protocolului de sesiuni. Pas cu pas: ghidul de host-uri.

Autorizare

bearerAuth

AutorizareBearer <token>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de /v1/realtime.

În: header

Parametri header

x-request-id?string

Id de corelare ales de client; e returnat ca x-codai-trace-id și persistat pe rândul de usage.

Lungimelength <= 128

Corpul răspunsului

`application/json`

curl -X GET "https://example.com/v1/hosts"

{  "hosts": [    {      "device_id": "2b6d8c1e-4f3a-4e9b-9c0d-7a1e5f6b8c2d",      "name": "codai desktop",      "platform": "desktop",      "os": "windows",      "hostname": "dragos-desktop",      "roots": [        "E:\\gh",        "C:\\Users\\me\\Projects"      ],      "since": 1758616800000,      "last_seen": 1758616845000    }  ]}

Autorizare

bearerAuth

AutorizareBearer <token>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de /v1/realtime.

În: header

Parametri query

os?string

Eticheta sistemului de operare al host-ului; trunchiată la 40 de caractere.

Lungimelength <= 40

hostname?string

Numele mașinii host; trunchiat la 120 de caractere.

Lungimelength <= 120

roots?string

Listă separată prin virgulă cu rădăcinile de fișiere expuse de host; golurile sunt eliminate, max 32 intrări.

Parametri header

x-request-id?string

Id de corelare ales de client; e returnat ca x-codai-trace-id și persistat pe rândul de usage.

Lungimelength <= 128

x-codai-device*string

UUID stabil al dispozitivului. Înregistrează dispozitivul la prima folosire (nume/platformă din x-codai-device-name / x-codai-device-platform) și selectează protocolul de sesiuni partajate.

Formatuuid

Corpul răspunsului

`text/event-stream`

`application/json`

curl -X GET "https://example.com/v1/hosts/stream" \  -H "x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08"

"string"

Autorizare

bearerAuth

AutorizareBearer <token>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de /v1/realtime.

În: header

Parametri de cale

deviceId*string

UUID-ul dispozitivului host țintă (din GET /v1/hosts).

Formatuuid

Parametri header

x-request-id?string

Id de corelare ales de client; e returnat ca x-codai-trace-id și persistat pe rândul de usage.

Lungimelength <= 128

x-codai-device*string

UUID stabil al dispozitivului. Înregistrează dispozitivul la prima folosire (nume/platformă din x-codai-device-name / x-codai-device-platform) și selectează protocolul de sesiuni partajate.

Formatuuid

Corpul cererii

application/json

Definiții TypeScript

Folosește tipul request body în TypeScript.

op*HostOp

Vocabularul de operații implementat de host-ul desktop.

Valoare în

"shell"
"fs_read"
"fs_write"
"fs_list"
"fs_roots"
"info"

args?

Argumente specifice operației, relayate ca atare (de ex. { cmd, cwd?, timeout_ms? } pentru shell, { path } pentru fs_list).

Implicit{}

timeout_ms?integer

Cât aștepți host-ul. Implicit 60000.

Interval1000 <= value <= 600000

label?string

Etichetă liberă afișată în UI-ul host-ului.

Lungimelength <= 200

Corpul răspunsului

`application/json`

curl -X POST "https://example.com/v1/hosts/497f6eca-6276-4993-bfeb-53cbbbba6f08/exec" \  -H "x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{    "op": "shell"  }'

{  "req_id": "b0b81fb9-c6eb-4a11-855e-45e48af9566f",  "ok": true,  "result": null,  "error": "string"}

Autorizare

bearerAuth

AutorizareBearer <token>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de /v1/realtime.

În: header

Parametri de cale

reqId*string

req_id-ul din evenimentul exec (UUID; malformat → 400).

Formatuuid

Parametri header

x-request-id?string

Id de corelare ales de client; e returnat ca x-codai-trace-id și persistat pe rândul de usage.

Lungimelength <= 128

x-codai-device*string

UUID stabil al dispozitivului. Înregistrează dispozitivul la prima folosire (nume/platformă din x-codai-device-name / x-codai-device-platform) și selectează protocolul de sesiuni partajate.

Formatuuid

Corpul cererii

application/json

Definiții TypeScript

Folosește tipul request body în TypeScript.

ok*boolean

Dacă operația a reușit pe host.

result?unknown

Orice JSON produs de operație (de ex. { stdout, stderr, exit_code } pentru shell); relayat ca atare. Forma e definită de desktop, nu de gateway.

error?string

Motivul eșecului, lizibil, când ok este false.

Lungimelength <= 4000

Corpul răspunsului

`application/json`

curl -X POST "https://example.com/v1/hosts/exec/497f6eca-6276-4993-bfeb-53cbbbba6f08/result" \  -H "x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{    "ok": true  }'

{  "ok": true}

200application/json

401application/json

402application/json

200text/event-stream

400application/json

401application/json

402application/json

403application/json

200application/json

400application/json

401application/json

402application/json

403application/json

404application/json

409application/json

504application/json

200application/json

400application/json

401application/json

402application/json

403application/json

`application/json`

`application/json`

`application/json`

`text/event-stream`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`