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.
Agenții văd ce host-uri sunt online prin unealta hosts_list a serverului MCP (doar citire; exec nu e expus prin MCP).
bearerAuthAutorizareBearer <codai_…>O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).
x-request-id?stringId de corelare ales de client; e returnat ca x-codai-trace-id și persistat pe rândul de usage.
length <= 128Host-urile conectate.
application/json- response
hosts*array<>curl -X GET 'https://ai.codai.ro/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" ], "caps": [ "iphone", "video" ], "environment_id": "7c1e2d3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f", "since": 1758616800000, "last_seen": 1758616845000 } ]}bearerAuthAutorizareBearer <codai_…>O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).
os?stringEticheta sistemului de operare al host-ului; trunchiată la 40 de caractere.
length <= 40hostname?stringNumele mașinii host; trunchiat la 120 de caractere.
length <= 120roots?stringListă separată prin virgulă cu rădăcinile de fișiere expuse de host; golurile sunt eliminate, max 32 intrări.
caps?stringListă separată prin virgulă cu capabilitățile oferite de host (iphone, video, pty, …); cel mult 16 intrări, fiecare potrivită cu ^[a-z0-9_-]{1,32}$, duplicatele sunt eliminate. O listă greșită dă 400.
env?stringUUID-ul mediului care servește stream-urile video / pty ale acestui host prin codai-relay. Dacă nu e un uuid → 400.
uuidx-request-id?stringId de corelare ales de client; e returnat ca x-codai-trace-id și persistat pe rândul de usage.
length <= 128x-codai-device*stringUUID 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.
uuidStream SSE (text/event-stream, cache-control: no-cache).
response?stringtext/event-streamcurl -X GET 'https://ai.codai.ro/v1/hosts/stream' \ -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08'"string"bearerAuthAutorizareBearer <codai_…>O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).
deviceId*stringUUID-ul dispozitivului host țintă (din GET /v1/hosts).
uuidx-request-id?stringId de corelare ales de client; e returnat ca x-codai-trace-id și persistat pe rândul de usage.
length <= 128x-codai-device*stringUUID 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.
uuidapplication/json- body
op*HostOpVocabularul de operații implementat de host-uri (codai desktop; iphone = bridge-ul codai pentru iPhone, capabilitatea iphone).
"shell""fs_read""fs_write""fs_list""fs_roots""info""iphone"args?Argumente specifice operației, relayate ca atare (de ex. { cmd, cwd?, timeout_ms? } pentru shell, { path } pentru fs_list). Pentru iphone trebuie să respecte HostIphoneArgs ({ tool, args? }), altfel 400.
{}timeout_ms?integerCât aștepți host-ul. Implicit 60000.
1000 <= value <= 600000label?stringEtichetă liberă afișată în UI-ul host-ului.
length <= 200Host-ul a răspuns (indiferent dacă ok este true sau false).
application/json- response
req_id*stringuuidok*booleanresult*unknownresult-ul host-ului, sau null când lipsește.
error*string|nullcurl -X POST 'https://ai.codai.ro/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"}bearerAuthAutorizareBearer <codai_…>O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).
reqId*stringreq_id-ul din evenimentul exec (UUID; malformat → 400).
uuidx-request-id?stringId de corelare ales de client; e returnat ca x-codai-trace-id și persistat pe rândul de usage.
length <= 128x-codai-device*stringUUID 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.
uuidapplication/json- body
ok*booleanDacă operația a reușit pe host.
result?unknownOrice 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?stringMotivul eșecului, lizibil, când ok este false.
length <= 4000Acceptat.
application/json- response
ok*truetruecurl -X POST 'https://ai.codai.ro/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}Ultima actualizare: