esh-pfi-infrastructure/stacks/althing-chamber/README.md

althing-chamber

Web UI + moderator daemon + agent-runner + Valkey IPC bridge for the althing inter-agent message bus. Four services on the compose default network. The chamber serves FastAPI/HTMX, the forseti daemon runs the moderation + curation loops, the agent-runner daemon claims floor grants for worldtree-driver agents and dispatches them to Worldtree's conversation API, and Valkey carries the Phase 3.1 cross-process streaming events (msg_start/delta/thinking/complete/curated) that are too high-volume to flow through SQLite. SQLite-backed state still shares between chamber + forseti + agent-runner via the bind-mount; streaming events ride pub/sub on the docker default network.

Server: ana-docker URL: http://10.250.50.70:7881 (configurable via .env) Upstream repo: vh/althing Image: althing-chamber:local — built on the host from the git repo by the deploy playbook. Not pulled from a registry.

Services in this stack

Container	Role	Port	Healthcheck
althing-chamber	FastAPI/HTMX web UI; SSE subscribers; /health endpoint	host 7881 → container 8000	python urllib /health
althing-forseti	Moderator + curator daemon; writes events that chamber's bridge picks up	— (no HTTP)	none (process-up signal only)
althing-agent-runner	Phase 2: claims worldtree-driver floor grants and dispatches to Worldtree's conversation API	— (no HTTP)	none (process-up signal only)
althing-valkey	Phase 3.1: Valkey 8 redis-protocol pub/sub bridge — carries streaming events from agent-runner → chamber	— (internal-only, valkey:6379 on default network)	valkey-cli ping

The three althing services (chamber/forseti/agent-runner) use the same ${ALTHING_IMAGE}; the command: line in compose picks which entrypoint runs in each container. Valkey is a stock upstream image (no custom build). chamber + agent-runner depends_on: valkey: service_healthy so the pub/sub bridge is up before either side starts publishing or subscribing.

The agent-runner is safe to enable preemptively — when no driver=worldtree handles are declared in config, it polls floor_grants and sleeps when the query returns empty. Multi-instance safe via the atomic UPDATE … WHERE consumed_at IS NULL claim primitive.

Deploy

Two paths — automated (preferred) and manual (escape hatch / first-time).

Automated (Gitea Actions, push-to-main)

The vh/althing repo ships .gitea/workflows/deploy.yaml. Every push to main + manual workflow_dispatch triggers the elway playbook below pinned to the triggering commit SHA. A reference copy of the workflow lives next to this README at gitea-workflow-deploy.yaml.example; the canonical source is in the vh/althing repo. The example header lists the two repo secrets required (DEPLOY_SSH_KEY, MGMT_REPO_TOKEN).

Manual (elway from a workstation)

# First deploy (or update to latest main)
scripts/elway ana-docker --playbook playbooks/deploy-althing-chamber.yaml

# Pin to a specific ref (tag, branch, or commit SHA)
scripts/elway ana-docker --playbook playbooks/deploy-althing-chamber.yaml --var ref=v0.1.0

Path layout (on ana-docker)

Host path	Container path	Purpose	Restic?
/opt/docker/build/althing-chamber/	—	git checkout used as docker build context	excluded
/opt/docker/compose/althing-chamber/	—	compose.yaml + .env	included (via /opt/docker)
/opt/docker/conf/althing-chamber/data/	/app/data	SQLite + state for BOTH services	included

Network model

Internal tooling, LAN-only. Chamber's container port 8000 is published on the host at 0.0.0.0:7881 (configurable via ALTHING_BIND / ALTHING_PORT); access is direct via http://10.250.50.70:7881. No Traefik, no TLS terminator, no public hostname.

Forseti has no port — it's a daemon. The two services communicate only via the shared SQLite file under the ${ALTHING_DATA_DIR} bind-mount; no docker network coupling beyond compose's default bridge.

Env-var contract

Var	In env?	In ~/.althing/config.yaml?	Notes
ALTHING_ROOT	✓ (set in compose)	n/a	Overrides the default ~/.althing/ dir. Container sets /app/data.
ALTHING_DB	✓ (set in compose)	n/a	Explicit SQLite path. Defaults to ${ALTHING_ROOT}/althing.db.
ALTHING_BIND	✓ (deploy-time)	also accepted	Bind address for the chamber HTTP server. Container always sets 0.0.0.0 internally.
ALTHING_PORT	✓ (deploy-time)	also accepted	Chamber listens here internally (always 8000 inside the container).

Env-var support for ALTHING_BIND / ALTHING_PORT was added on the galdrabok side as part of the container-deploy cycle (env > config.yaml

defaults precedence).

First-deploy sequence (when galdrabok's Dockerfile lands)

1. Generate a deploy keypair on ana-docker (private stays on host; pubkey lands in ~lkraven/.ssh/authorized_keys).
2. Wire two secrets in vh/althing Actions settings:
   • DEPLOY_SSH_KEY — the private key from step 1.
   • MGMT_REPO_TOKEN — Gitea PAT with read:repository on this repo, used by the workflow to clone the management repo for the playbook.
3. Push to vh/althing's main branch (or trigger workflow_dispatch); the Actions runner clones both repos, configures SSH, runs scripts/elway ana-docker --playbook playbooks/deploy-althing-chamber.yaml --var ref=$SHA.
4. Playbook: clones into /opt/docker/build/althing-chamber, builds the image, uploads compose + .env (one-time seed), brings both services up, polls /health until 200.