@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 two 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.

Requirements

• Docker (running) — tasks are containers.
• Node ≥ 20.

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 and sends the cloud only a hash — the secret never leaves the machine (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 via an enrollment token (writes config)
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

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

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.