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 host is a registered machine that can run agent sessions. When a session is created with a host_id, the Omnigent server routes it to that specific host. The host daemon (omnigent host) keeps a WebSocket tunnel open to the server and listens for launch commands. Hosts expose their filesystem to the server’s directory picker, letting users select a workspace before a session starts.

​
CLI Registration

To register the current machine as a host, run the daemon in the foreground: 
omnigent host <server_url>
For example: 
omnigent host https://omnigent.example.com
The daemon connects to the server, registers the machine, and keeps the connection alive. While the daemon is running, the host appears as online in GET /v1/hosts and can receive runner launch requests. When the daemon exits, the host transitions to offline — existing sessions on that host continue until they naturally end, but no new runners can be launched.

​
List Hosts


GET /v1/hosts Returns all hosts owned by the authenticated user — both online and offline. Response: 
{
  "hosts": [
    {
      "id": "host_a1b2c3d4",
      "name": "Alice's MacBook Pro",
      "status": "online",
      "platform": "darwin",
      "registered_at": 1700000000,
      "runner_count": 2
    }
  ]
}
​
id
string
Opaque host identifier, e.g. "host_a1b2c3d4e5f6...".
​
name
string
Human-readable machine name (hostname).
​
status
string
"online" when the daemon’s tunnel is active; "offline" otherwise.
​
platform
string
Host operating system, e.g. "darwin", "linux", "win32".
​
registered_at
integer
Unix epoch timestamp of first registration.
​
runner_count
integer
Number of active runners currently running on this host.

​
Get Host


GET /v1/hosts/{host_id} Returns details for a single host. Path parameter: host_id — the host identifier. Errors:
  • 404 — host not found
  • 403 — caller does not own the host

​
Browse Host Filesystem (Root)


GET /v1/hosts/{host_id}/filesystem Lists the contents of the host daemon’s home directory. Used by the web UI’s workspace directory picker to show the root view. The host expands ~ itself. Query parameters:
​
limit
integer
default:"20"
Maximum entries per page. Range: 1–1000.
​
after
string
Forward pagination cursor (entry path).
​
before
string
Backward pagination cursor.
Response: 
{
  "object": "list",
  "data": [
    { "name": "projects", "path": "/Users/alice/projects", "type": "directory" },
    { "name": "Downloads", "path": "/Users/alice/Downloads", "type": "directory" }
  ],
  "has_more": false
}
Errors:
  • 404 — host not found
  • 403 — caller does not own the host
  • 409 — host is offline
  • 504 — host timed out

​
Browse Host Filesystem (Path)


GET /v1/hosts/{host_id}/filesystem/{path} Lists the contents of a specific directory on the host. Accepts an absolute path or a tilde-prefixed path (e.g. ~/foo). The host expands ~ itself. Path parameters: host_id, path (absolute or tilde-prefixed path on the host). Query parameters: same as the root filesystem endpoint (limit, after, before). Errors:
  • 400 — path validation failed
  • 404 — host or path not found
  • 403 — caller does not own the host
  • 409 — host is offline
  • 502 — host I/O error
  • 504 — host timed out

​
Launch Runner on Host


POST /v1/hosts/{host_id}/runners Launches a runner on a specific host for an existing session. The server generates a binding token, writes the expected runner ID to the session row, sends the launch command to the host, and waits for the host’s acknowledgement.
​
session_id
string
required
Session to bind the new runner to, e.g. "conv_abc123".
​
workspace
string
required
Absolute path on the host to use as the runner’s working directory, e.g. "/Users/alice/projects/api". When git is set, this is the source repository directory.
​
git
object
Optional git worktree options. When set, the server creates a worktree for a new branch off workspace.
Response: 
{
  "runner_id": "runner_0123456789abcdef",
  "status": "launching"
}
Errors:
  • 400 — session already has a runner bound
  • 403 — caller does not own the host
  • 404 — host not found
  • 409 — host is offline

Build docs developers (and LLMs) love

Get started for freeTalk to us