Files
sam 0346bfef77 fix(configuration): require containers.image instead of a private-registry default (#2054)
applyContainerDefaults no longer fills containers.image with a hard-coded
private-registry reference. An unset image now fails configuration
validation with 'containers.image is required for autonomous workflow
workers', so a fresh instance is told at startup (and via the readiness
probe at runtime) instead of at the first failed container pull.

Configs that relied on the default now set it explicitly: dev.toml (the
local task image:agent build, which e2e also overlays), plus commented
[containers] blocks in config.example.toml and standalone.toml. The
deploy docs no longer describe a code-level default.
2026-11-21 01:16:41 +11:00

7.0 KiB

Running this distribution

This archive holds the linux/amd64 binary for each service. Each service owns its data and reaches the others only through their gRPC contracts (or NATS, for task actions):

Service Owns Reaches
archie-state-store tasks, events, control-plane settings, identities and access policies, installed packages (PostgreSQL) nothing
archie-gateway conversations (PostgreSQL, its own tables) and every model call: chat turns, curators, MCP tools and sampling State Store; daemon over NATS for task actions
archied dispatch: forge polling, the task queue, the embedded NATS broker, agent containers State Store; Gateway
archie-messaging the Telegram, email and webhook channel connections Gateway; State Store for channel settings
archie-ui the dashboard and the webhook capture receiver Gateway; State Store

Without archie-messaging the channels are simply absent, so it needs a unit of its own (deployments/systemd-user-service.md).

archie-agent (the per-task sandboxed runtime) has no unit of its own. The agent image is a separate thing, pulled for the containers archied spawns per task: [containers].image has no default, and the daemon reports it as missing at startup. This archive's release.json pins the digest the release published, and the deploy step passes it to the install, so a release install needs nothing by hand; a from-source install sets the image itself. Set [containers].registry_auth when the reference is on a registry that needs a login -- see deployments/systemd-user-service.md#6-pinning-the-archie-agent-image.

Quickstart

  1. Pick a starting configuration. The full set of annotated templates lives in this repository's deployments/ directory on GitHub (https://offloaded.dev) — standalone.toml (no forge, the simplest start), single-forge-github.toml and docker-nats-stack.toml cover the common cases. Every one needs PostgreSQL 18 with the archie_migrator and archie_runtime roles created once by archie-state-store provision (see deployments/README.md); docker compose up -d postgres plus that command gives the local default. Copy whichever fits to:

    mkdir -p ~/.config/archie
    cp <template>.toml ~/.config/archie/config.toml
    
  2. Edit config.toml (forge token, repos, [services.state] target, model providers) and place any secrets in ~/.config/archie/env or referenced secret:// locations.

  3. Start the five processes. Order does not matter: a service whose peer is not up yet waits for it and reports it as degraded on its health surface meanwhile. The Gateway waits for the daemon's NATS endpoint when the broker is embedded.

    ./archie-state-store -config ~/.config/archie/config.toml -listen 127.0.0.1:9090 &
    ./archie-gateway     -config ~/.config/archie/config.toml -listen 127.0.0.1:8585 &
    ./archie-messaging   -config ~/.config/archie/config.toml &
    ./archie-ui          -config ~/.config/archie/config.toml &
    ./archied            -config ~/.config/archie/config.toml
    

    Open [web].listen (default 127.0.0.1:8484) to configure the organisation, workspace and first administrator account. Remote access requires an HTTPS reverse proxy. Complete setup before exposing the dashboard publicly.

  4. For a persistent, 24/7 deployment instead of a foreground run, follow the systemd user-unit runbook: https://offloaded.dev.

Version

This archive's binaries are built from the archied release tag in its filename; archie-ui, archie-gateway, archie-state-store and archie-messaging ship at that same version rather than being independently tagged (see RELEASING.md in the source repository for why only archied and archie-agent are independently versioned).

archie-state-store, archie-gateway, archie-messaging, archie-ui and archied are services that must be running and addressable; archie-messaging carries the Telegram, email and webhook channels since the v1.30.0 extraction, so an install (or an upgrade across v1.30.0) needs its unit as well -- see deployments/systemd-user-service.md.

Native self-update

Install on Settings → Status runs archied update install -version X against the release source in the update settings. It fetches release vX, refuses it unless the source's key signed its statement, and downloads the Linux/amd64 zip only if it hashes to the digest that statement names. Every host binary in the zip must report X. It then pulls the agent image the statement pins by digest, backs up the database to db.pre-update.dump in the state directory, stages the new binaries beside the live ones and hands the transaction to archied update watchdog in a process of its own (a transient systemd user unit). Nothing that runs changes until the watchdog takes over.

archied update check finds the newest GitHub release with a linux-amd64 zip on the channel chosen under Settings → Status → Updates: stable, next (includes prereleases) or a pinned version. From a shell it reads ARCHIE_UPDATE_RELEASE_CHANNEL and ARCHIE_UPDATE_PIN, or -channel and -pin. The notification destination remains separate from the release channel.

release.json supplies the service order and required config sections to both first-install and self-update. A missing unit or config section produces an ordered migration plan and refuses installation. Apply that plan before retrying. Automatic topology edits are intentionally unsupported.

The watchdog stops the units in reverse release.json order, switches the staged executables by rename, switches the control-plane image policy (only the image field, with conflict detection), and restarts the units in order through systemctl --user. archied must report the new version and stay healthy for 120 seconds. Otherwise the watchdog restores the previous binaries and image policy. Data is not rolled back unless the new release migrated the database: then the previous binaries cannot serve it, so the pre-update backup is restored and the outcome report says that every write since the update began is gone. Without a systemd user manager the watchdog switches binaries and image policy but restarts nothing, and the install reports that the services need a manual restart.

Transactions live in ${XDG_STATE_HOME:-~/.local/state}/archie/update, outside the binary directory: transaction/journal.json, transaction/previous/, and transaction/archied, the frozen copy of the archied that wrote the journal. On daemon boot, an interrupted transaction is handed to that frozen watchdog with -recover before normal startup: a transaction that never started is discarded, one that was switching or observing is rolled back, and a decided one is finished. To recover manually, run transaction/archied update watchdog -recover -bin-dir ~/.local/bin from that state directory. A failed recovery keeps the journal for another attempt.

The database backup stays in the state directory after a committed update for manual recovery with archie-state-store restore.