Files
archie/deployments

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.

  • standalone.toml: start here. Event-driven automation with no forge or repositories, local Ollama models, loopback services and no tokens.

  • 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-messaging -config ~/.config/archie/config.toml &
archie-ui -config ~/.config/archie/config.toml &
archied -config ~/.config/archie/config.toml
# or via systemd:
systemctl --user start archied

Start order does not matter: a service waits for its peers and reports them as degraded meanwhile. Every template needs PostgreSQL 18 at database_url; docker compose up -d postgres provides the default one.

The State Store service (archie-state-store) owns the task data in the PostgreSQL database database_url names and serves the StateStore gRPC contract. BOTH archied and archie-gateway dial it via [services.state].target and never open the task tables themselves. The templates set [services.state] accordingly: a host-only agent reaches a loopback bind (127.0.0.1:9090), while a container-mode agent needs the Docker bridge gateway address, because a container cannot reach the host's loopback. A non-loopback address needs [tls] certificates from your own CA; see config.example.toml.

Running the dashboard

The dashboard is served by the standalone UI Service (archie-ui), not by archied. 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

Open the dashboard to configure the organisation, workspace and first administrator account. Use HTTPS through a reverse proxy for remote access, and complete setup before exposing it publicly. 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.

The dashboard speaks plain HTTP. A non-loopback bind therefore carries the session cookie and the provider token in clear over the network, and archie-ui warns about exactly that at startup. Terminate TLS in front of it (a reverse proxy or the tunnel itself) and set [web].trust_forwarded_headers = true to declare the proxy and silence the warning; leaving it off while exposing the port directly is the case the warning names.

Auth note: archie-ui authenticates to its dependencies with its [tls] certificate (archie-ui.pem).

# 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 ([tls] required)
archie-state-store -config ~/.config/archie/config.toml -listen 172.17.0.1:9090

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 holds the state-store ownership lock on its database; archied and archie-gateway never open the task tables directly, so a second store process on the same database_url refuses to start, and a consumer that opens the task tables indicates dual-store ownership. 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.