Hosts
The relay that lets a phone run an operation on your desktop: presence stream, exec and result.
A host is a device that keeps GET /v1/hosts/stream open. Another device posts an exec; the gateway relays it over that stream and blocks until the host posts the result or the timeout fires. Presence expires 45 s after the last heartbeat. This relay is best-effort and not part of the public sessions protocol spec. Walkthrough: hosts guide.
Agents see which hosts are online through the MCP server tool hosts_list (read-only; exec is not exposed over MCP).
bearerAuthAuthorizationBearer <codai_…>A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).
x-request-id?stringClient correlation id; echoed back as x-codai-trace-id and persisted on the usage row.
length <= 128Connected hosts.
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 } ]}bearerAuthAuthorizationBearer <codai_…>A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).
os?stringHost operating system label; truncated to 40 chars.
length <= 40hostname?stringHost machine name; truncated to 120 chars.
length <= 120roots?stringComma-separated list of filesystem roots the host exposes; blanks dropped, max 32 entries.
caps?stringComma-separated capabilities the host offers (iphone, video, pty, …); at most 16 entries, each matching ^[a-z0-9_-]{1,32}$, duplicates dropped. A malformed list is a 400.
env?stringUUID of the environment that serves video / pty streams for this host over codai-relay. Not a uuid → 400.
uuidx-request-id?stringClient correlation id; echoed back as x-codai-trace-id and persisted on the usage row.
length <= 128x-codai-device*stringStable device UUID. Registers the device on first use (name/platform from x-codai-device-name / x-codai-device-platform) and selects the shared-sessions protocol.
uuidSSE stream (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"bearerAuthAuthorizationBearer <codai_…>A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).
deviceId*stringDevice UUID of the target host (from GET /v1/hosts).
uuidx-request-id?stringClient correlation id; echoed back as x-codai-trace-id and persisted on the usage row.
length <= 128x-codai-device*stringStable device UUID. Registers the device on first use (name/platform from x-codai-device-name / x-codai-device-platform) and selects the shared-sessions protocol.
uuidapplication/json- body
op*HostOpOperation vocabulary hosts implement (codai desktop; iphone = the codai iPhone bridge, cap iphone).
"shell""fs_read""fs_write""fs_list""fs_roots""info""iphone"args?Op-specific arguments, relayed verbatim (e.g. { cmd, cwd?, timeout_ms? } for shell, { path } for fs_list). For iphone they must match HostIphoneArgs ({ tool, args? }), else 400.
{}timeout_ms?integerHow long to wait for the host. Default 60000.
1000 <= value <= 600000label?stringFree-form label shown in the host UI.
length <= 200The host answered (whether ok is true or false).
application/json- response
req_id*stringuuidok*booleanresult*unknownThe host's result, or null when absent.
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"}bearerAuthAuthorizationBearer <codai_…>A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).
reqId*stringThe req_id from the exec event (UUID; malformed → 400).
uuidx-request-id?stringClient correlation id; echoed back as x-codai-trace-id and persisted on the usage row.
length <= 128x-codai-device*stringStable device UUID. Registers the device on first use (name/platform from x-codai-device-name / x-codai-device-platform) and selects the shared-sessions protocol.
uuidapplication/json- body
ok*booleanWhether the op succeeded on the host.
result?unknownAny JSON produced by the op (e.g. { stdout, stderr, exit_code } for shell); relayed as-is. Shape is defined by the desktop, not the gateway.
error?stringHuman-readable failure reason when ok is false.
length <= 4000Accepted.
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}Last updated: