Files
archie/deployments
sam 13d32f34b0 fix(webui): retry event pump priming until the state store answers
archie-ui binds before archie-state-store is guaranteed to be listening, so
the first prime is routinely refused. PumpEvents returned on that error, which
left the activity feed history-only for the life of the process. Prime now
retries with capped backoff and gives up only when the context ends.

Orders archie-ui.service after archie-state-store.service as well, which
narrows the window without closing it: After= sequences the start, it does
not wait for the listener.
2026-09-18 23:59:40 +10:00
..

Archie Core Deployment Examples

This directory contains configuration templates and guides for different deployment scenarios of Archie Core.

Directory Structure

  • single-forge-github.toml: Standard single-forge deployment managing multiple GitHub repositories under a single bot account and GitHub token.

  • multi-forge-github-gitea.toml: Multi-identity deployment running GitHub and a self-hosted Gitea instance simultaneously with distinct bot accounts, tokens, and repository sets.

  • local-ollama-standalone.toml: Self-hosted deployment running local LLM models via Ollama (e.g., llama3, qwen2.5) with optional standalone (forge-disabled) operation.

  • docker-nats-stack.toml: Host-run archied orchestrating sandboxed archie-agent containers over the repository's Compose-managed NATS service. Copy to ~/.config/archie/config.toml, start NATS with Compose, then start archied on the host.

  • systemd-user-service.md: Operational runbook for running archied as a persistent 24/7 background service via systemd user units and loginctl enable-linger.


Usage

Copy any scenario template to your XDG configuration directory (${XDG_CONFIG_HOME:-~/.config}/archie/config.toml):

mkdir -p ~/.config/archie
cp deployments/single-forge-github.toml ~/.config/archie/config.toml

Edit API keys in ~/.config/archie/env or directly in config.toml, then launch Archie Core:

archie-gateway -config ~/.config/archie/config.toml -listen 127.0.0.1:8585 &
archie-state-store -config ~/.config/archie/config.toml -listen 127.0.0.1:9090 &
archie-ui -config ~/.config/archie/config.toml &
archied -config ~/.config/archie/config.toml
# or via systemd:
systemctl --user start archied

The templates use the extracted Gateway Service by default. Start archie-gateway before archied; it owns the conversation SQLite file and serves the ChatContract gRPC API on the configured target.

The State Store service (archie-state-store) owns the single archie.db task SQLite file and serves the StateStore gRPC contract. After the in-process store path was deleted, BOTH archied and archie-gateway dial it via [services.state].target and never open archie.db themselves (docs/prds/state-store-contract.md §12 step 7). The templates set [services.state] accordingly: a host-only agent reaches a loopback bind (127.0.0.1:9090) with no token, while a container-mode agent needs the Docker bridge gateway address plus a matching bearer token (target_token / --token / STATE_STORE_TOKEN), because a container cannot reach the host's loopback.

Running the dashboard

The dashboard is served by the standalone UI Service (archie-ui), not by archied (UI cutover, archie-core-8cda.5.4; docs/prds/ui-service-boundary.md). It reads the same config.toml, dials the Gateway and State Store targets already configured there, and binds [web].listen (127.0.0.1:8484 by default). Start it after the Gateway and the State Store:

archie-ui -config ~/.config/archie/config.toml

A non-loopback [web].listen requires a dashboard token (-token, or -token-file to mint and persist one); a loopback bind needs none. archied runs no dashboard listener at all, so webhook capture (POST /webhooks/capture/{source}) is received by archie-ui and the binding-dispatch loop in archied consumes what arrives from the shared State Store.

Auth note: unlike archied, archie-ui has no secret registry -- GATEWAY_TOKEN/STATE_STORE_TOKEN resolve from its process environment only (or from [services.*].target_token in config.toml), so whatever starts archie-ui must export those tokens into its environment. See the UI Service unit in systemd-user-service.md for the worked example.

# loopback (host-only agent)
archie-state-store -config ~/.config/archie/config.toml -listen 127.0.0.1:9090
# or container-mode: bind the bridge gateway with a token
archie-state-store -config ~/.config/archie/config.toml -listen 172.17.0.1:9090 -token <token>

Verifying the daemon

archied always serves its own liveness surface on [health].listen (127.0.0.1:8485 by default). It answers 503 for the whole of boot and 200 once the daemon is running, which is what makes it a usable restart check:

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8485/healthz      # 200 = daemon running, 503 = still booting
curl -s http://127.0.0.1:8485/health/detailed                               # readiness probes, 503 when degraded

The update watchdog polls this address after restarting the daemon and rolls the release back when it never answers, so a deployment that moves it must change [health].listen rather than relying on the script's fallback. The dashboard's /healthz is a separate surface on [web].listen and reports the dashboard's process, not the daemon's.

Verifying the State Store

archie-state-store exposes an optional HTTP readiness surface when launched with -ready-addr (the systemd unit uses 127.0.0.1:9091). Use it to confirm the process is up and the store is healthy before starting archied:

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:9091/healthz        # 200 = process up
curl -s http://127.0.0.1:9091/health/detailed                                # state_db component -> 200, or 503 when degraded

A running State Store owns exactly one task SQLite file (<db_path>-tasks.sqlite); archied and archie-gateway never open archie.db directly, so a second store process on the same db_path, or a consumer that opens the task file, indicates dual-store ownership (docs/prds/state-store-contract.md §12 step 7/8). The readiness probe is the single-writer check the runbook has against a degraded store: a 503 from /health/detailed means archied should be started only after the store is healthy.