@runuai/host 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Diogo Perillo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# @runuai/host
+
+The **host** for [Uai](https://github.com/runuai/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
+
+```bash
+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):
+
+```bash
+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](https://github.com/runuai/uai/blob/main/docs/decisions.md)
+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](https://github.com/privatenumber/tsx); there is
+no build step (ADR-032).
+
+## More
+
+- [Uai on GitHub](https://github.com/runuai/uai)
+- [docs/host-ui.md](https://github.com/runuai/uai/blob/main/docs/host-ui.md) — the local UI surface.
+- [docs/host-packaging.md](https://github.com/runuai/uai/blob/main/docs/host-packaging.md) — how this package is built and published.
+</content>

package/bin/uai-host.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * Published entrypoint for `@runuai/host` (ADR-032).
+ *
+ * The host ships TypeScript source and runs it through tsx — no build step —
+ * so every runtime path (drizzle migrations, scripts/agent/*.sh, the
+ * images/standard build context) resolves off its source file exactly as in
+ * dev. This shim registers tsx's ESM loader, then hands off to src/cli.ts.
+ * argv passes straight through: src/cli.ts reads process.argv.slice(2).
+ */
+import { register } from "tsx/esm/api";
+
+register();
+await import(new URL("../src/cli.ts", import.meta.url).href);

package/db/migrations/0000_host_tasks.sql

@@ -0,0 +1,12 @@
+CREATE TABLE `uai_host_tasks` (
+  `task_id` text PRIMARY KEY NOT NULL,
+  `code_server_port` integer,
+  `preview_ports` text DEFAULT '[]' NOT NULL,
+  `compose_project` text,
+  `worktree_path` text,
+  `status_mirror` text,
+  `locked_at` integer,
+  `started_at` integer,
+  `ended_at` integer,
+  `updated_at` integer DEFAULT (unixepoch() * 1000) NOT NULL
+);

package/db/migrations/0001_host_ui.sql

@@ -0,0 +1,11 @@
+ALTER TABLE `uai_host_tasks` ADD `owner_user_id` text;--> statement-breakpoint
+ALTER TABLE `uai_host_tasks` ADD `owner_email` text;--> statement-breakpoint
+ALTER TABLE `uai_host_tasks` ADD `project_slugs` text DEFAULT '[]' NOT NULL;--> statement-breakpoint
+CREATE TABLE `uai_host_events` (
+  `id` text PRIMARY KEY NOT NULL,
+  `task_id` text NOT NULL,
+  `kind` text NOT NULL,
+  `ts` integer DEFAULT (unixepoch() * 1000) NOT NULL,
+  `detail` text
+);--> statement-breakpoint
+CREATE INDEX `uai_host_events_ts_idx` ON `uai_host_events` (`ts`);

package/db/migrations/0002_host_github_tokens.sql

@@ -0,0 +1,8 @@
+CREATE TABLE `host_github_tokens` (
+  `user_id` text PRIMARY KEY NOT NULL,
+  `installation_id` integer NOT NULL,
+  `refresh_token_ct` blob NOT NULL,
+  `refresh_token_nonce` blob NOT NULL,
+  `refresh_token_expires_at` integer,
+  `updated_at` integer NOT NULL
+);

package/db/migrations/0003_host_ssh_keys.sql

@@ -0,0 +1,8 @@
+CREATE TABLE `host_ssh_keys` (
+  `user_id` text PRIMARY KEY NOT NULL,
+  `public_key` text NOT NULL,
+  `private_key_ct` blob NOT NULL,
+  `private_key_nonce` blob NOT NULL,
+  `created_at` integer NOT NULL,
+  `updated_at` integer NOT NULL
+);

package/db/migrations/0004_host_owner_name.sql

@@ -0,0 +1 @@
+ALTER TABLE `uai_host_tasks` ADD `owner_name` text;

package/db/migrations/meta/_journal.json

@@ -0,0 +1,41 @@
+{
+  "version": "7",
+  "dialect": "sqlite",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "6",
+      "when": 1779900001000,
+      "tag": "0000_host_tasks",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "6",
+      "when": 1779900002000,
+      "tag": "0001_host_ui",
+      "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "6",
+      "when": 1779900003000,
+      "tag": "0002_host_github_tokens",
+      "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "6",
+      "when": 1779900004000,
+      "tag": "0003_host_ssh_keys",
+      "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "6",
+      "when": 1779900005000,
+      "tag": "0004_host_owner_name",
+      "breakpoints": true
+    }
+  ]
+}

package/db/schema.ts

@@ -0,0 +1,82 @@
+/**
+ * Host-local SQLite schema (ADR-020).
+ *
+ * The cloud DB owns metadata and lifecycle. Each host owns only the runtime
+ * fields needed to recover containers, discover local ports, and tunnel
+ * editor/preview traffic.
+ */
+
+import { sql } from "drizzle-orm";
+import { blob, integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
+
+export const hostTasks = sqliteTable("uai_host_tasks", {
+  taskId: text("task_id").primaryKey(),
+  codeServerPort: integer("code_server_port"),
+  previewPorts: text("preview_ports").notNull().default("[]"),
+  composeProject: text("compose_project"),
+  worktreePath: text("worktree_path"),
+  statusMirror: text("status_mirror"),
+  // Owner + project slugs — received in TaskLaunchInput at task-up and
+  // persisted here so the local UI (ADR-028) can show "who/what" without a
+  // cloud round-trip. The cloud stays the audit authority.
+  ownerUserId: text("owner_user_id"),
+  ownerEmail: text("owner_email"),
+  ownerName: text("owner_name"),
+  projectSlugs: text("project_slugs").notNull().default("[]"),
+  lockedAt: integer("locked_at", { mode: "number" }),
+  startedAt: integer("started_at", { mode: "number" }),
+  endedAt: integer("ended_at", { mode: "number" }),
+  updatedAt: integer("updated_at", { mode: "number" })
+    .notNull()
+    .default(sql`(unixepoch() * 1000)`),
+});
+
+export type HostTask = typeof hostTasks.$inferSelect;
+export type NewHostTask = typeof hostTasks.$inferInsert;
+
+// Host-side task lifecycle event log (ADR-028). HostEvent (the agent-output
+// stream) is forwarded to the cloud, not stored; this table is the local
+// `/api/events` feed — appended on task.created/started/ended (+ ship).
+export const hostEvents = sqliteTable("uai_host_events", {
+  id: text("id").primaryKey(), // ulid
+  taskId: text("task_id").notNull(),
+  kind: text("kind").notNull(), // task.created | task.started | task.ended | task.ship
+  ts: integer("ts", { mode: "number" })
+    .notNull()
+    .default(sql`(unixepoch() * 1000)`),
+  detail: text("detail"),
+});
+
+export type HostEventRow = typeof hostEvents.$inferSelect;
+export type NewHostEventRow = typeof hostEvents.$inferInsert;
+
+// GitHub user refresh token, encrypted at rest with the host master key
+// (ADR-027). The ONLY place a GitHub secret lives at rest. Access tokens are
+// never stored — they go straight into the container's gh config.
+export const githubTokens = sqliteTable("host_github_tokens", {
+  userId: text("user_id").primaryKey(),
+  installationId: integer("installation_id").notNull(),
+  refreshTokenCt: blob("refresh_token_ct").notNull(),
+  refreshTokenNonce: blob("refresh_token_nonce").notNull(),
+  refreshTokenExpiresAt: integer("refresh_token_expires_at"),
+  updatedAt: integer("updated_at").notNull(),
+});
+
+export type GithubToken = typeof githubTokens.$inferSelect;
+export type NewGithubToken = typeof githubTokens.$inferInsert;
+
+// Per-user ed25519 SSH key (ADR-029). Generated ON the host; the private key
+// lives encrypted at rest with the host master key (same secret-blind pattern
+// as host_github_tokens — ADR-015). The cloud only ever sees `public_key`,
+// which the user pastes into GitHub. Keyed by the internal cloud user id.
+export const sshKeys = sqliteTable("host_ssh_keys", {
+  userId: text("user_id").primaryKey(),
+  publicKey: text("public_key").notNull(), // OpenSSH "ssh-ed25519 AAAA… uai-<user>"
+  privateKeyCt: blob("private_key_ct").notNull(),
+  privateKeyNonce: blob("private_key_nonce").notNull(),
+  createdAt: integer("created_at").notNull(),
+  updatedAt: integer("updated_at").notNull(),
+});
+
+export type SshKey = typeof sshKeys.$inferSelect;
+export type NewSshKey = typeof sshKeys.$inferInsert;

package/images/standard/Dockerfile

@@ -0,0 +1,232 @@
+# syntax=docker/dockerfile:1.7
+#
+# uai standard image — the ONE per-host workbench image (ADR-022).
+#
+# Built once per host at host startup and cached as `uai-standard:dev`.
+# A task reuses this image unchanged unless a selected project declares an
+# `extra` snippet, in which case task-up derives `uai-task-<id>` FROM this
+# image. See ../../../docs/runtime.md.
+#
+# Design points:
+#   - Debian bookworm-slim base, non-root `node` user (home /home/node).
+#   - asdf at /opt/asdf with plugins for nodejs/python/golang/ruby/rust.
+#     Concrete runtime versions are installed lazily at task-up by uai-init,
+#     cached on the host-wide named volume mounted at /opt/asdf-data.
+#   - A default ~/.tool-versions (asdf global fallback) pins a working Node +
+#     Python so the agent CLIs and a 0-project scratchpad always have a runtime;
+#     a project's own .tool-versions takes precedence (asdf dir walk).
+#   - Claude Code + Codex + code-server installed globally via the root Node.
+#
+# This Dockerfile takes NO build args and substitutes NO placeholders — it is
+# fully static. Per-task variation lives in the derived `uai-task-<id>` image.
+
+FROM debian:bookworm-slim
+
+# ---------------------------------------------------------------------------
+# 0. Pinned versions (single source of truth for this image).
+# ---------------------------------------------------------------------------
+
+# asdf release to clone. Pinned for reproducible builds; bump deliberately.
+ENV ASDF_VERSION=v0.14.1
+
+# ---------------------------------------------------------------------------
+# 1. System packages.
+#
+# build-essential + the -dev libs cover what asdf's nodejs/python/ruby/rust
+# build plugins need to compile a runtime from source on first use. unzip is
+# needed by several asdf plugins; gnupg + ca-certificates for the gh apt repo.
+# ---------------------------------------------------------------------------
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends \
+      build-essential \
+      ca-certificates \
+      curl \
+      direnv \
+      git \
+      gnupg \
+      jq \
+      libbz2-dev \
+      libffi-dev \
+      liblzma-dev \
+      libncurses-dev \
+      libreadline-dev \
+      libsqlite3-dev \
+      libssl-dev \
+      libxml2-dev \
+      libxmlsec1-dev \
+      libyaml-dev \
+      openssh-client \
+      pkg-config \
+      procps \
+      ripgrep \
+      tk-dev \
+      tmux \
+      unzip \
+      xz-utils \
+      zlib1g-dev \
+      zsh \
+ && rm -rf /var/lib/apt/lists/*
+
+# GitHub CLI (`gh`) — used by the ship/PR flow inside the container.
+RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
+      | tee /usr/share/keyrings/githubcli-archive-keyring.gpg >/dev/null \
+ && chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg \
+ && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
+      > /etc/apt/sources.list.d/github-cli.list \
+ && apt-get update \
+ && apt-get install -y --no-install-recommends gh \
+ && rm -rf /var/lib/apt/lists/*
+
+# uv — fast Python package + venv manager (used by uai-init's Python path).
+# Installed system-wide so both root and node can run it.
+RUN curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR=/usr/local/bin sh
+
+# ---------------------------------------------------------------------------
+# 2. Non-root `node` user.
+#
+# The container runs as `node`; uai-init and the agent CLIs expect
+# /home/node. uid/gid 1000 matches the common host default so bind-mounted
+# worktree files stay writable.
+# ---------------------------------------------------------------------------
+
+RUN groupadd --gid 1000 node \
+ && useradd --uid 1000 --gid 1000 --create-home --home-dir /home/node --shell /bin/bash node
+
+# ---------------------------------------------------------------------------
+# 3. asdf.
+#
+# Clone to /opt/asdf (the code) and point the DATA dir at /opt/asdf-data
+# (the host-wide cache volume mounts there). Both root and node must be able
+# to read the install and write the data dir, so /opt/asdf-data is group
+# owned by `node` and group-writable; the data volume inherits this.
+# ---------------------------------------------------------------------------
+
+ENV ASDF_DIR=/opt/asdf
+ENV ASDF_DATA_DIR=/opt/asdf-data
+# Leave the tool-versions filename at asdf's default (`.tool-versions`) so asdf
+# walks UP from the cwd and a project's /workspace/<slug>/.tool-versions wins.
+# The baked default lives at the node user's home (~/.tool-versions) as asdf's
+# global fallback for tasks with no project file (agent CLIs, scratchpad).
+# Do NOT set ASDF_DEFAULT_TOOL_VERSIONS_FILENAME to an absolute path — that
+# overrides the search *filename* and bypasses project files entirely (it made
+# asdf read only /etc/.tool-versions, ignoring per-project pins).
+
+RUN git clone --depth 1 --branch "$ASDF_VERSION" https://github.com/asdf-vm/asdf.git "$ASDF_DIR" \
+ && mkdir -p "$ASDF_DATA_DIR" \
+ && chown -R node:node "$ASDF_DIR" "$ASDF_DATA_DIR" \
+ && chmod -R g+rwX "$ASDF_DATA_DIR"
+
+# Make asdf available on PATH + shell init for BOTH root and node, for login
+# and non-login shells (uai-init runs as node via a non-interactive exec).
+#   - asdf.sh sources the shim + completions and prepends the shims dir.
+#   - The shims dir is also added to PATH directly so a bare `docker exec`
+#     (which sources neither profile) still sees installed runtimes.
+ENV PATH=/opt/asdf-data/shims:/opt/asdf/bin:$PATH
+
+RUN printf '%s\n' \
+      '. /opt/asdf/asdf.sh' \
+      > /etc/profile.d/asdf.sh \
+ && chmod 0644 /etc/profile.d/asdf.sh
+
+# Source asdf from each user's bashrc as well (interactive non-login shells,
+# e.g. the code-server terminal) and enable direnv.
+RUN for rc in /root/.bashrc /home/node/.bashrc; do \
+      printf '\n%s\n%s\n' \
+        '. /opt/asdf/asdf.sh' \
+        'eval "$(direnv hook bash)"' >> "$rc"; \
+    done \
+ && chown node:node /home/node/.bashrc
+
+# zsh + oh-my-zsh as the interactive login shell for `node` (the code-server
+# terminal and `docker exec -it`). Installed unattended; the installer writes a
+# default ~/.zshrc (robbyrussell theme, git plugin) which we extend with the
+# same asdf + direnv wiring as .bashrc. Non-interactive execs (uai-init, claude,
+# codex, git) invoke their command directly, so the login-shell change does not
+# affect them.
+RUN su node -c 'sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)" "" --unattended' \
+ && printf '\n%s\n%s\n' \
+      '. /opt/asdf/asdf.sh' \
+      'eval "$(direnv hook zsh)"' >> /home/node/.zshrc \
+ && chown node:node /home/node/.zshrc \
+ && usermod -s /usr/bin/zsh node
+
+# ---------------------------------------------------------------------------
+# 4. asdf plugins + the root default runtimes.
+#
+# Plugins are added for all common runtimes; only the root defaults are
+# *installed* at build time. Other versions are installed lazily by uai-init
+# and cached on the /opt/asdf-data volume.
+#
+# Run as node so the install lands in /opt/asdf-data owned by node.
+# ---------------------------------------------------------------------------
+
+# Default .tool-versions at the node user's home = asdf's GLOBAL fallback, used
+# only when no project /workspace/<slug>/.tool-versions is in scope (agent CLIs,
+# scratchpad tasks). A project file takes precedence via asdf's dir walk. The
+# `tool-versions` file in this directory is the AUTHORITATIVE source.
+COPY tool-versions /home/node/.tool-versions
+RUN chmod 0644 /home/node/.tool-versions \
+ && chown node:node /home/node/.tool-versions
+
+USER node
+
+# Add plugins for all common runtimes, then install exactly the versions the
+# default ~/.tool-versions pins (read straight from the file so there is one
+# source of truth). Other versions install lazily at task-up via uai-init.
+RUN bash -lc '\
+  set -e; \
+  . /opt/asdf/asdf.sh; \
+  asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git; \
+  asdf plugin add python https://github.com/asdf-community/asdf-python.git; \
+  asdf plugin add golang https://github.com/asdf-community/asdf-golang.git; \
+  asdf plugin add ruby   https://github.com/asdf-vm/asdf-ruby.git; \
+  asdf plugin add rust   https://github.com/asdf-community/asdf-rust.git; \
+  cd /home/node && asdf install nodejs && asdf install python; \
+'
+
+# ---------------------------------------------------------------------------
+# 5. Global agent CLIs + code-server, via the root-default Node.
+#
+# These are Node programs and must be present even for a 0-project task, so
+# they are installed globally against the asdf-default Node and then reshimmed
+# so `claude` / `codex` / `code-server` resolve through the asdf shims dir
+# (which is on PATH for a bare docker exec).
+# ---------------------------------------------------------------------------
+
+RUN bash -lc '\
+  set -e; \
+  . /opt/asdf/asdf.sh; \
+  npm install -g @anthropic-ai/claude-code @openai/codex; \
+  curl -fsSL https://code-server.dev/install.sh | sh -s -- --method standalone --prefix /home/node/.local; \
+  asdf reshim nodejs; \
+'
+
+ENV PATH=/home/node/.local/bin:$PATH
+
+# ---------------------------------------------------------------------------
+# 6. uai-init baked in.
+# ---------------------------------------------------------------------------
+
+USER root
+
+COPY --chown=root:root container/uai-init /usr/local/bin/uai-init
+RUN chmod 0755 /usr/local/bin/uai-init
+
+# Curated code-server defaults. uai-init seeds these into the per-task User
+# settings dir when none exists (slim chrome, telemetry off, trust off).
+COPY --chown=root:root container/code-server-settings.json /usr/local/share/uai/code-server-settings.json
+
+# ---------------------------------------------------------------------------
+# 7. Default working directory + entrypoint.
+#
+# The container is a long-lived workbench. uai-init (deps + code-server) and
+# the agent CLIs are started by the host via `docker exec` after task-up.
+# ---------------------------------------------------------------------------
+
+USER node
+WORKDIR /workspace
+
+CMD ["sleep", "infinity"]

package/images/standard/README.md

@@ -0,0 +1,122 @@
+# Uai standard image
+
+The single per-host workbench image, built once at host startup and cached as
+`uai-standard:dev` (ADR-022). Every task reuses it unchanged unless a selected
+project declares an [`extra`](../../../docs/runtime.md#the-extra-escape-hatch)
+snippet, in which case task-up derives `uai-task-<id>` FROM this image.
+
+See [`docs/runtime.md`](../../../docs/runtime.md) for the authoritative spec.
+
+## What's inside
+
+- **Base**: `debian:bookworm-slim`, non-root `node` user (home `/home/node`,
+  uid/gid 1000). The container runs as `node`; uai-init and the agent CLIs
+  expect `/home/node`.
+- **asdf** at `/opt/asdf`, data dir `/opt/asdf-data` (the host-wide
+  `uai-asdf-data` volume mounts there). Plugins pre-added for `nodejs`,
+  `python`, `golang`, `ruby`, `rust`. Only the root defaults are installed at
+  build time; other versions install lazily at task-up via `uai-init` and are
+  cached on the data volume.
+- **Default `~/.tool-versions`** (asdf's global fallback, at `/home/node`)
+  pinning a default Node + Python. The `tool-versions` file in this directory is
+  the authoritative source for the numbers; the `Dockerfile` `COPY`s it to
+  `/home/node/.tool-versions` and installs exactly those versions at build time.
+  This guarantees the agent CLIs and a 0-project scratchpad always have a
+  runtime. asdf uses its default `.tool-versions` filename and walks UP from the
+  cwd, so a project's `/workspace/<slug>/.tool-versions` **takes precedence**;
+  the home file is only the fallback. (Do **not** set
+  `ASDF_DEFAULT_TOOL_VERSIONS_FILENAME` to an absolute path — that overrides the
+  search filename and makes asdf ignore per-project files.)
+- **uv uses asdf's Python.** For Python folders, `uai-init` runs
+  `uv venv --python "$(asdf which python)"` so the venv matches the asdf-pinned
+  version (`.tool-versions`) rather than uv's own `.python-version` /
+  `requires-python` discovery, which can disagree or be junk.
+- **Claude Code** + **Codex**, installed globally via the root-default Node
+  (`@anthropic-ai/claude-code`, `@openai/codex`), reshimmed onto the asdf
+  shims dir so `claude` / `codex` resolve under a bare `docker exec`.
+- **code-server** (the Editor pane), **gh**, **git**, **curl**,
+  **ca-certificates**, **jq**, **ripgrep**, **tmux**, **direnv**, **uv**,
+  plus `build-essential` and the `-dev` libraries asdf's build plugins need.
+- **`uai-init`** baked at `/usr/local/bin/uai-init`.
+- `WORKDIR /workspace`; `CMD ["sleep","infinity"]`.
+
+Codex credentials are **not** baked in or mounted — task-up `docker cp`s them
+into `/home/node/.codex` at init (ADR-015 keeps secrets host-side). `~/.claude`
+is bind-mounted read-only by the generated compose.
+
+## Pinned constants (must match the rest of the host runtime)
+
+| Thing | Value |
+| --- | --- |
+| Standard image tag | `uai-standard:dev` |
+| Per-task derived image (only with `extra`) | `uai-task-<taskId>` |
+| Shared asdf data volume | `uai-asdf-data` → `/opt/asdf-data` |
+| Compose service name | `app` (container `task-<taskId>-app-1`) |
+| In-container workspace | `/workspace` |
+| code-server port | `8080` (inside the container) |
+
+## Build
+
+The host process builds this at startup when the cached digest is missing or
+stale. To build by hand from the repo root:
+
+```bash
+docker build -t uai-standard:dev host-agent/images/standard
+```
+
+A derived per-task image (when a project has `extra`) is built by `task-up`
+from a generated `.uai/Dockerfile` that is `FROM uai-standard:dev` plus the
+concatenated `extra` RUN lines, tagged `uai-task-<id>`.
+
+## Smoke test (no uai involved)
+
+These files are validated at the Phase E smoke test (no Docker in CI), so the
+steps below are for local image iteration only.
+
+```bash
+# 1. Build.
+docker build -t uai-standard:dev host-agent/images/standard
+
+# 2. Create the shared asdf data volume + a throwaway workspace.
+docker volume create uai-asdf-data
+mkdir -p /tmp/uai-smoke/workspace/demo
+printf 'nodejs 22.11.0\n' > /tmp/uai-smoke/workspace/demo/.tool-versions
+printf '{"name":"demo","packageManager":"npm@10"}\n' \
+  > /tmp/uai-smoke/workspace/demo/package.json
+
+# 3. Run the container the way compose would (service `app`, workspace bind,
+#    asdf cache volume, code-server port published on loopback).
+docker run -d --name uai-smoke \
+  -v /tmp/uai-smoke/workspace:/workspace \
+  -v uai-asdf-data:/opt/asdf-data \
+  -p 127.0.0.1::8080 \
+  uai-standard:dev
+
+# 4. Sanity-check the baked toolchain (bare exec — no profile sourced).
+docker exec uai-smoke bash -lc 'asdf --version && node -v && python --version'
+docker exec uai-smoke claude --version
+docker exec uai-smoke codex --version
+
+# 5. Run uai-init: per-folder asdf install + deps, then code-server on 8080.
+docker exec uai-smoke /usr/local/bin/uai-init
+docker exec uai-smoke bash -lc 'curl -sf http://127.0.0.1:8080/healthz || \
+  curl -sf -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8080/'
+
+# 6. Tear down.
+docker rm -f uai-smoke
+```
+
+Expected: step 4 prints the asdf version and the root-default Node + Python;
+`claude` / `codex` resolve; step 5 launches code-server bound to
+`0.0.0.0:8080` and the HTTP probe returns a 2xx/3xx.
+
+## Notes / gotchas
+
+- **Bash 3.2 constraint does NOT apply here.** `uai-init` runs on the Linux
+  base image (bash 5) and may use `shopt`, arrays, etc. The 3.2 constraint is
+  only for host scripts under `host-agent/scripts/agent/`.
+- **First-use asdf cost.** The first task needing a given runtime version pays
+  the download/build time; results persist on `uai-asdf-data` for every later
+  task on the host.
+- **`uai-init` always exits 0.** A failing per-folder install logs and is
+  skipped so one bad repo never blocks task-up; code-server is still launched.