HostAgentics Docs

HostAgentics Runtime Adapters

Last updated: 2026-08-06

Runtime adapters (`packages/runtime-core` plus `runtime-n8n`, `runtime-openclaw`, `runtime-hermes`) are the layer that translates a generic provisioning plan into a concrete runtime: they build the environment, define the health check, and know the image, ports, and persistence layout for each runtime kind. This document is an internal engineering reference. Image references below are the tested defaults from the version catalog; production deployments are always digest-pinned (floating tags are forbidden).

1. Adapter contract

Every adapter implements `RuntimeAdapter` (`packages/runtime-core`):

  • **Environment builder** — a pure function of the runtime context (config, secrets, entitlements, shard coordinates) that returns the runtime's environment variables. Secrets come from the decrypted per-runtime secret scope and are never shared across runtimes.
  • **Health check (`verify`)** — probes the runtime's own health endpoint and returns `{ healthy, latencyMs, detail }`. Provisioning cannot reach `running`, and restores cannot be marked completed, until a real health probe passes.
  • **Provisioning plan** — the ordered steps (allocating capacity → creating service → creating storage → configuring runtime → assigning domain → deploying → checking health → finalizing access) with customer-safe labels.
  • **Lifecycle operations** — configure, restart, pause, resume, update (deploy a pinned target version), rotate secrets, create/restore backups, apply resource plan, delete.
  • **Ports and persistence** — each adapter declares the container port(s) and volume mount paths for its runtime.

    • 2. n8n adapter (`runtime-n8n`)

  • **Image**: official n8n image, tested default `n8nio/n8n:2.33.4` (digest-pinned; source: Docker Hub, release notes on GitHub).
  • **Port**: 5678 (editor/webhook). Health check: `GET <base>/healthz` must return OK.
  • **Persistence**: n8n data volume mounted at `/home/node/.n8n`, plus a dedicated PostgreSQL service (`postgres:16-alpine`) with its own volume at `/var/lib/postgresql/data` — n8n runtimes always get a dedicated database, never a shared one.
  • **Required secrets**: `db-password` (generated per runtime) and `encryption-key` (`N8N_ENCRYPTION_KEY`, unique per runtime). Provisioning fails fast if either is missing.
  • **Environment highlights**: `DB_TYPE=postgresdb`, `N8N_EDITOR_BASE_URL`/`WEBHOOK_URL` set to the branded HTTPS base URL, `N8N_PROTOCOL=https`, diagnostics and personalization disabled, `N8N_TEMPLATES_ENABLED=false`, and concurrency set from entitlements (`N8N_CONCURRENCY_PRODUCTION_LIMIT`, `QUEUE_CONCURRENCY`).
  • **License gate**: n8n provisioning is blocked unless the commercial license arrangement is confirmed (see `docs/n8n-license-gate.md`).

    • 3. OpenClaw adapter (`runtime-openclaw`)

  • **Image**: official OpenClaw production image from GHCR (the primary registry per official docs), tested default `ghcr.io/openclaw/openclaw:2026.7.1-2` (digest-pinned).
  • **Port**: gateway on **18789**. Health check: any HTTP response from the gateway — including a `401` auth challenge — proves the process is live and enforcing authentication; a response without an auth challenge is treated as unhealthy.
  • **Persistence**: state volume at `/home/node/.openclaw` (configuration + workspaces + agent state); auth-profile encryption keys are kept separate under `/home/node/.config/openclaw`. One gateway cell per tenant, matching the official multi-tenant model.
  • **Required secret**: `gateway-token` (`OPENCLAW_GATEWAY_TOKEN`), generated per runtime and stored encrypted.
  • **Model access**: `OPENROUTER_API_KEY` is set to a restricted per-runtime key (managed credit) or the customer's BYOK key; the platform management key is never injected.
  • **Channels**: guided channel setup covers web chat, Telegram, Discord, Slack, and WhatsApp.

    • 4. Hermes Agent adapter (`runtime-hermes`)

  • **Image**: official Nous Research Hermes Agent image, tested default `nousresearch/hermes-agent:v2026.8.3` (digest-pinned; source: Docker Hub).
  • **Container model**: single container using the official entrypoint and s6 supervision tree — `/init` is PID 1, the gateway runs as the main program, and the dashboard is a supervised service enabled via `HERMES_DASHBOARD=1`. The default entrypoint is never bypassed.
  • **Dashboard port**: **9119** (`HERMES_DASHBOARD_HOST=0.0.0.0`, `HERMES_DASHBOARD_PORT=9119`). The dashboard is **never exposed unauthenticated**: basic-auth username, password, and secret are required secrets; provisioning fails if they are missing.
  • **Health check**: `GET <base>/api/status` on the dashboard port; an OK response or a `401` (auth enforced) counts as healthy.
  • **Persistence**: all customer data (memories, skills, profiles) persists under `/opt/data` (`HERMES_HOME`, `HERMES_WRITE_SAFE_ROOT`).
  • **Optional API server**: an OpenAI-compatible API server can be enabled with `API_SERVER_KEY` (authenticated) for Relay/external use.

    • 5. Shared invariants

  • Secrets are generated per runtime, stored encrypted, and injected only at deploy/configure time; they are never logged.
  • Health checks use real probes against the runtime's own endpoint — completion is never simulated.
  • Resource plans (CPU/RAM) are applied to the provider service (`applyResourcePlan`) and concurrency is enforced at the runtime layer where the image supports it.

    • 6. Related documents

  • `docs/n8n-deployment.md`, `docs/openclaw-deployment.md`, `docs/hermes-deployment.md` — provisioning flows per kind
  • `docs/updates.md` — how the version catalog drives adapter updates
  • `docs/secret-rotation.md` — per-runtime secret purposes