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.

Authorization

bearerAuth

AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

`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    }  ]}

Authorization

bearerAuth

AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Query Parameters

os?string

Host operating system label; truncated to 40 chars.

Lengthlength <= 40

hostname?string

Host machine name; truncated to 120 chars.

Lengthlength <= 120

roots?string

Comma-separated list of filesystem roots the host exposes; blanks dropped, max 32 entries.

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

x-codai-device*string

Stable 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.

Formatuuid

Response Body

`text/event-stream`

`application/json`

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

"string"

Authorization

bearerAuth

AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Path Parameters

deviceId*string

Device UUID of the target host (from GET /v1/hosts).

Formatuuid

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

x-codai-device*string

Stable 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.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

op*HostOp

Operation vocabulary the desktop host implements.

Value in

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

args?

Op-specific arguments, relayed verbatim (e.g. { cmd, cwd?, timeout_ms? } for shell, { path } for fs_list).

Default{}

timeout_ms?integer

How long to wait for the host. Default 60000.

Range1000 <= value <= 600000

label?string

Free-form label shown in the host UI.

Lengthlength <= 200

Response Body

`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"}

Authorization

bearerAuth

AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Path Parameters

reqId*string

The req_id from the exec event (UUID; malformed → 400).

Formatuuid

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

x-codai-device*string

Stable 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.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

ok*boolean

Whether the op succeeded on the host.

result?unknown

Any 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?string

Human-readable failure reason when ok is false.

Lengthlength <= 4000

Response Body

`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`