LLM appliance: hub daemon, mesh chat, shared join widget, CI/CD to httpeers.net

[mkotelnikov]

What this is

The LLM appliance, the mesh chat that uses it, and now its production deployment:

• apps/hub: the Node hub daemon. It has a persistent identity, rules, service modules (llm, a LiteLLM passthrough that mints keys), a local door, an admin REST API and a local admin UI.
• apps/llm-chat: a chat for any OpenAI-compatible API. It runs standalone (index.html) or over the mesh (mesh.html: join, discover the hub's LLM service, chat).
• deploy/llm-appliance: hub, LiteLLM, Postgres and Traefik in compose. It uses the relay-circuit fallback when WebRTC fails.
• New in this round:
  • CI/CD to httpeers.net. .github/workflows/llm-appliance.yml publishes ghcr.io/statewalker/httpeers-hub (the image carries the appliance's compose files under /appliance). A forced-command SSH key then deploys it to /opt/httpeers-llm on the server, with verification and rollback.
  • OpenRouter models (compose.server.yml, litellm/config.server.yaml).
  • packages/httpeers-join: one shared join widget, used by mesh.html and by the demos' app, images and proxy pages.

CI/CD mechanism

• Push to main touching the hub, the packages, deploy/llm-appliance or the lockfile: publish pushes sha-<commit> and latest. Then deploy runs, gated on vars.LLM_DEPLOY_ENABLED == 'true', and SSHes in with LLM_DEPLOY_SSH_KEY.
• The key is authorised as restrict,command="/opt/httpeers-llm/bin/deploy.sh". It can only pass a commit sha.
• On the server the script pulls that sha's image, extracts /appliance into releases/<sha>, and runs compose up --wait. It then checks that the peerId is unchanged, that health.sh passes, and that LiteLLM lists models. When a check fails it rolls back.
• Why not the relay's SSH pattern or a pull-based updater: see deploy/llm-appliance/README.md, "On the httpeers.net server".
• Pull requests build the image without pushing it.

New configuration (names only): secret LLM_DEPLOY_SSH_KEY, variables LLM_DEPLOY_ENABLED=true and DEPLOY_KNOWN_HOSTS. It reuses the existing secrets DEPLOY_HOST and DEPLOY_USER. The OpenRouter key lives only in the server's /opt/httpeers-llm/.env (mode 600).

Merging this deploys. It republishes the hub image as latest and redeploys the appliance from main. The lockfile changes, so the relay and sites workflows also rebuild and redeploy (a brief relay reconnect).

Verified

• CD. It was exercised from this branch before merge through a temporary trigger, since reverted. Five deploy runs: one failed on LiteLLM's slow first start, which led to the fix in compose.server.yml; one failed on a Traefik readiness race, where the rollback path ran and the fix is in deploy.sh; the rest passed.
• E2E on the real domains (deploy/llm-appliance/e2e/RESULTS.md): all six steps pass against the server, through https://llm-chat.httpeers.net/mesh.html and relay.httpeers.net, with browsers on a different network from the server:
  • admin join with a direct link, key mint, and a streamed gpt-4o-mini reply;
  • the LiteLLM dashboard over the mesh;
  • a member on the relay path refused admin paths, then chatting;
  • revocation effective 65 ms after the DELETE.
• Join widget:
  • 38 package tests (happy-dom, every phase, and a runtime import of dist/);
  • workspace build, typecheck and tests green (run in the branch's worktree);
  • join-smoke for the demos;
  • a live paste-to-join on the published mesh.html, joined direct in 1.25 s.
• Not verified: a phone on mobile data against the server hub, and a real camera QR scan (headless has no camera).

Not in this PR

• The demos pages with the widget are not published (another branch is publishing hub. and app.).
• *.p.httpeers.net is Session origins: {name}.p.httpeers.net shell, demo, infra #3.
• Open question. The first PR CI run failed in apps/hub/tests/daemon.test.ts cleanup with ENOTEMPTY on hub/state, which means a state write landed after stop() resolved. The cleanup now retries, and the check passes. Whether the daemon should await its pending state writes in stop() is left open.

🤖 Generated with Claude Code