State Store service

Stored data

archie-state-store keeps archie's task and execution records in PostgreSQL. The daemon, dashboard and other services read and change those records through its gRPC API.

The State Store holds:

• Tasks, status changes, execution steps, events and task logs.
• Captured events, mappings, bindings and dispatch records.
• Stored configuration, resource revisions and installed packages.
• Accounts, organisations, access policies and task credentials.

The gateway manages conversation storage separately. Don't assume stopping the State Store stops every writer to the PostgreSQL database.

Connect to the service

The installer creates the archie-state-store systemd user service. Its default gRPC address is 127.0.0.1:9090.

In config.toml, target tells clients where to connect:

[services.state]
target = "127.0.0.1:9090"

The State Store normally listens on that address too. Set listen when it needs to bind to a different address, or use its -listen flag. Clients continue to use target.

The State Store opens the PostgreSQL database named by database_url and applies schema migrations at startup. It won't start if it can't open or migrate the database. A second State Store pointing at the same database is refused, so run one State Store process per database.

Clients require a State Store target. An empty target is a configuration error; it doesn't select an in-process database.

Connect across hosts

Plaintext gRPC is allowed only on loopback.

For a listener or client target outside loopback, configure [tls] with ca_file and cert_dir.

Service clients authenticate with their service certificates. Task clients use a task credential and trust the State Store's certificate authority. A task credential permits only the supported operations for its own task, and stops working when it's revoked or expires.

Check health

The installed service exposes HTTP health checks on 127.0.0.1:9091, separately from gRPC.

Check whether the process is responding:

curl -i http://127.0.0.1:9091/healthz

Check whether its database is ready:

curl -i http://127.0.0.1:9091/health/detailed

/healthz returns 200 when the HTTP listener is up. /health/detailed runs the state_db probe and returns 503 if it fails. Use the detailed check before treating the State Store as ready for work.

If you're starting the binary yourself, enable these endpoints with -ready-addr:

archie-state-store -ready-addr 127.0.0.1:9091

Without that flag, the standalone command doesn't start an HTTP health listener. If you installed with a different port base, use the readiness address from its systemd unit.

Restart and diagnose failures

systemctl --user restart archie-state-store
systemctl --user status archie-state-store
journalctl --user -u archie-state-store -e

Service clients wait for the State Store to reconnect during a restart, subject to each call's deadline. Check /health/detailed after the restart; a running process alone doesn't confirm database readiness.

For a named instance such as dev, use archie-state-store-dev in these commands.

Back up and recover

To take a consistent snapshot while archie is running:

archie-state-store backup -out /path/to/archie.dump

To check the database and the configuration the daemon would load:

archie-state-store validate

Recovery commands use database_url from the selected configuration. Pass -config /path/to/config.toml when you're working with a different configuration. Backup and restore require pg_dump and pg_restore on PATH.

To restore a snapshot, stop every archie service first. Restore replaces the database and discards writes made after the snapshot. It refuses to proceed while an archie service still holds a database ownership claim.

archie-state-store restore -from /path/to/archie.dump

Schema migrations aren't rolled back automatically. To return to the database state before a migration, restore a snapshot taken before it.