Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/omnigent-ai/omnigent/llms.txt

Use this file to discover all available pages before exploring further.

A runner is the Python subprocess that executes an agent session’s LLM loop and tools. Runners connect to the Omnigent server over a WebSocket tunnel, receive task inputs, execute them using the configured harness (Claude SDK, OpenAI Agents, Codex, etc.), and stream events back to the server for broadcast to connected clients. Each runner is bound to exactly one session.
Runners are not deployed separately — they run on user machines or cloud sandboxes (the host). The server acts as the message broker between runners and clients. When a host is registered with omnigent host, it spawns runners on demand when the server sends a launch command.

​
Runner Lifecycle

When a session starts, the following sequence occurs:
  1. The server creates the session row and waits for a runner to connect.
  2. If a host_id is set, the server sends a POST /v1/hosts/{host_id}/runners launch command to the host daemon, which spawns a Python subprocess (the runner).
  3. If no host_id is set, the runner connects directly from the CLI or SDK (omnigent run).
  4. The runner opens a WebSocket tunnel to the server and advertises its capabilities (harnesses, tools).
  5. The session’s runner_id is written and runner_online flips to true in health checks.
  6. The runner receives task inputs from the server, executes the LLM loop, and streams events back.
  7. When the session ends (user deletes it, agent completes, or interrupt is issued), the runner exits cleanly and the tunnel closes.
Runners appear in GET /v1/runners while their tunnel is open, and disappear from the listing when they exit. The session row retains the runner_id even after the runner disconnects; runner_online reflects real-time tunnel state.

​
List Runners


GET /v1/runners Returns currently online runners owned by the requesting user. When authentication is active, only runners whose tunnel was established by the same user are returned. Without auth (local/dev mode), all online runners are listed. Response: 
{
  "data": [
    {
      "id": "runner_0123456789abcdef",
      "session_id": "conv_abc123",
      "harnesses": ["claude-sdk", "codex"],
      "status": "online"
    }
  ]
}
​
id
string
Stable runner identifier, e.g. "runner_0123456789abcdef".
​
session_id
string
Session this runner is bound to.
​
harnesses
array
Harness types this runner supports, e.g. ["claude-sdk", "codex"].
​
status
string
"online" when the tunnel is active.

​
Get Runner Status


GET /v1/runners/{runner_id}/status Returns whether a specific runner currently has an open WebSocket tunnel. When authentication is active, a runner owned by a different user appears as offline (to prevent enumeration). Path parameter: runner_id — the runner identifier. Response: 
{
  "runner_id": "runner_0123456789abcdef",
  "online": true
}
​
runner_id
string
The runner identifier echoed from the request.
​
online
boolean
true when the runner has an active tunnel; false when offline or not visible to the caller.

​
Checking Runner Status via Health Endpoint

The /health endpoint provides a convenient way to check runner (and host) status for one or more sessions in a single request: 
# Single session
curl "http://localhost:6767/health?session_id=conv_abc123"

# Multiple sessions (batch)
curl "http://localhost:6767/health?session_ids=conv_abc,conv_def,conv_ghi"

{
  "status": "ok",
  "session": {
    "id": "conv_abc123",
    "runner_online": true,
    "host_online": true
  }
}
The batch form uses a single SQL IN query rather than N per-ID round trips, making it efficient for polling many sessions (e.g. the web sidebar).

Build docs developers (and LLMs) love

Get started for freeTalk to us