# Archive Clients

One Python daemon runs as either an `archive` or `cache` node for Archive
Control. Both roles use the same code and `sodium/archive-clients` image.

The current foundation provides strict TOML configuration, file-backed secrets,
API/local root mapping, fail-fast permission and sparse-file probes, a durable
SQLite command inbox, bounded one-writer WebSocket output, registration-first
authentication, heartbeat handling, duplicate-command acknowledgements, and
indefinite capped exponential reconnect with optional jitter.

```bash
archive-client --config /etc/archive-control/client.toml --check-config
archive-client --config /etc/archive-control/client.toml --mode archive
```

`--mode` accepts only `archive` or `cache` and overrides the configured role.
Secrets must be regular files without group/world permissions. The daemon never
stores them in SQLite or sends the shared token after registration.

This foundation currently executes heartbeat and state-snapshot commands.
Other mutation commands are durably rejected as unsupported until their
service and file-operation executors are added; they are never falsely
acknowledged as accepted.

Run tests and build using containers:

```bash
docker build --target test -t archive-clients-test .
docker run --rm archive-clients-test
docker build -t sodium/archive-clients:dev .
```

Generated bindings are pinned to archive-control-proto commit
`4ec852014dad74606d4078b3ae1aa208c814b033`.