@runuai/host

The host for Uai — a self-hosted service that runs parallel AI coding tasks in ephemeral Docker containers on a machine you control. This package is the long-running per-user daemon that connects your machine to the Uai cloud and runs the task containers locally. It also serves a small read-only monitor UI on 127.0.0.1 (ADR-028).

One process does three things:

• Cloud bridge — a host-initiated outbound WSS to wss://app.runuai.com/host carrying every command/tunnel. The cloud never connects in; nothing inbound is exposed.
• Local UI — an HTTP server on 127.0.0.1:5876 (next free port if taken): connection badge, service info, active tasks, recent events. Localhost only, no auth, read-only — mutations come from the cloud, not here.
• MCP gateway — a credential-injecting HTTP proxy for task containers, bound to 127.0.0.1:5877 by default. Listener failures retry with capped backoff and are advertised to the cloud as bounded health state.

Requirements

• Docker (running) — tasks are containers.
• Node 22, 24, 25 or 26; Node 24 LTS recommended. Those are the majors the pinned SQLite dependency ships a prebuilt binary for. Tested release majors are 22, 24 and 26; Node 25 warns and continues when the binding loads. Anything else — including Node 20, 21 and 23 — has to compile from source and fails on a machine without a C++ toolchain.

Install & enroll

npm i -g @runuai/host

Then, in the Uai web app, open an organization and choose “Add a host.” It mints a one-time enrollment token and shows the exact command to run on this machine (ADR-031):

uai-host setup --cloud wss://app.runuai.com/host --enroll uaienroll_…
uai-host install      # per-user service: launchd (macOS) / systemd --user (Linux)
uai-host start

The host generates its own bridge credential locally. The cloud persists only its hash; the raw credential transits authenticated TLS for bridge auth and existing-host attachment but is not stored there (ADR-015). Once started it appears in your org and can run tasks. Data + config live under ~/.uai (~/.uai/.env.local, ~/.uai/data/); from a repo checkout they stay under the repo instead. The monitor UI is at http://127.0.0.1:5876 (exact port in uai-host status).

CLI (uai-host)

setup --cloud <wss-url> --enroll <token>
                     claim this machine, or enroll its existing identity in
                     the token's workspace
enroll <token> [--cloud <wss-url>]
                     first-time setup, or attach this machine to another
                     workspace; uses the stored cloud URL when available
install [--dry-run]  install as a per-user service for this OS
uninstall            remove the service
start | stop         control the installed service
restart              stop + start
status               connection, service info, active tasks (same data as the UI)
logs [--follow]      tail the service log
run                  run in the foreground (debug)
pair <token>         store a host token directly (manual fallback for setup)
open                 open the local UI in your browser

enroll is available in host version 0.9.15 and newer. Its compatible cloud endpoint is intentionally deployed before that host release.

--dry-run on install (and start/stop/…) prints the unit file + load commands without touching launchd/systemd.

Headless

Runs identically with no display: install via the same flow, skip uai-host open, and use uai-host status for everything the UI shows. The UI stays reachable over an SSH port-forward to 127.0.0.1:5876 if you want it.

At boot, task and channel starts wait for the initial agent-CLI maintenance pass to settle before any in-container writer or runner executes. The cloud host page shows this short preparation state. It also shows MCP gateway listener failures while the host retries them; gateway health is independent of ordinary task admission.

Security

Tasks run in ephemeral containers and do not mount your live AI session dirs. Per-task credentials (GitHub tokens, SSH keys) are decrypted only on the host, using a host-resident master key; the cloud stores only hashes and public keys. See ADR-015 for the secret-blind model.

Dev (from a repo checkout)

pnpm host-agent (from the repo root) = uai-host run — the service in the foreground, no install, logs to stdout. The packaged binary runs the same TypeScript source through tsx; there is no build step (ADR-032).

More

• Uai on GitHub
• docs/host-ui.md — the local UI surface.
• docs/host-packaging.md — how this package is built and published.

Telemetry

Installed hosts report crashes only to Sentry by default. Sent on a crash: the error and stack trace (paths and secret-shaped strings redacted), recent bridge-connection breadcrumbs, OS/runtime versions, the package version, and a pseudonymous host id. No sessions, no usage pings, and no request data — nothing is sent until something actually crashes. Telemetry is designed to exclude chat, prompts, env values, and repo content; error text is scrubbed for secret shapes, but redaction is pattern-based, not perfect. Repo checkouts and dev/test runs never report, and reporting only activates after this notice has been shown once (the install/pair/setup/start/restart commands print it — a silently upgraded service stays off until one of them runs).

Opt out any time — add to $UAI_HOME/.env.local (default ~/.uai/.env.local), then uai-host restart:

UAI_TELEMETRY_DISABLED=1

UAI_SENTRY_DSN=<dsn> redirects reports to your own Sentry instead.