Daemon Runtime

Athena supports separate runtime binaries without changing the configuration contract. athena_rs remains the main API and CLI process, while the athena-daemon workspace package exposes worker binaries that all load the same config.yaml, the same .env beside that config file, and the same control-plane or logging tables.

Default Behavior

cargo run -- starts athena_rs and boots the API server directly.
When daemon.enabled is false, athena_rs also starts inline legacy workers, the deferred query worker, backup workers, and the Typesense sync worker when those toggles are enabled.
Clone jobs can be created through the API, but clone execution never runs inside athena_rs.

Runtime Ownership Matrix

Profile	Processes to run	`daemon.enabled`	Worker ownership	When to use
Default bundled API	`athena_rs`	`false`	`athena_rs` owns inline legacy, deferred, backup, and Typesense workers	simplest local and single-process deployment
Split API + bundled daemon	`athena_rs` and `athena_daemon`	`true`	`athena_daemon` owns clone execution plus deferred, backup, Typesense, and optional legacy workers	normal production split
Hybrid clone-only	`athena_rs` and `athena_clone_worker`	usually `false`	`athena_clone_worker` owns clone execution while `athena_rs` keeps the other inline workers	first split step when clone jobs need their own supervisor
Fully specialized worker-per-process	`athena_rs` plus one dedicated binary per worker family	`true`	each worker family is assigned to a dedicated binary	fine-grained supervision, scaling, or focused debugging

Important nuance: only clone execution can be split out while leaving daemon.enabled off. Backup, deferred, Typesense, and legacy workers do not currently have a per-family "external only, inline off" switch.

Binary Matrix

Binary	Package	Owns	Typical use
`athena_rs`	root package	HTTP API, CLI entrypoint, optional inline workers	default runtime from the repo root
`athena_daemon`	`athena-daemon`	clone worker, deferred worker, backup workers, Typesense worker, optional legacy workers	bundled background runtime
`athena_clone_worker`	`athena-daemon`	clone worker only	separate clone execution without moving the other families
`athena_backup_worker`	`athena-daemon`	backup schedule and execution workers only	worker-per-process or focused backup debugging
`athena_deferred_query_worker`	`athena-daemon`	deferred gateway queue worker only	worker-per-process or focused deferred queue debugging
`athena_typesense_worker`	`athena-daemon`	Typesense sync worker only	worker-per-process or focused search-sync debugging
`athena_daemon_legacy_workers`	`athena-daemon`	connection monitor, outbox relay, registry reconnect, optional vacuum health collector	worker-per-process or migration away from inline legacy startup

Shared Bootstrap Contract

All runtime binaries still share the same operator contract:

ATHENA_CONFIG_PATH and the normal config search path resolve the same config.yaml
.env is loaded from beside the resolved config file
client bootstrap still uses the same registry and logging database
clone and backup runtimes still depend on pg_dump and pg_restore
worker ownership is still published into the same control-plane runtime registry

The split is process ownership and supervision, not a separate deployment configuration model.

Deployment Rules

Keep daemon.enabled: false when athena_rs should continue to own legacy, deferred, backup, and Typesense workers inline.
Set daemon.enabled: true when those daemon-owned families will be started outside the API process.
Use athena_clone_worker as the only supported "split one family first" topology. It is safe because clone execution is never owned by athena_rs.
Do not run two runtimes that can claim the same worker family.
Do not assume a healthy API process means clone jobs will execute; clone jobs require either athena_daemon or athena_clone_worker.

Common Commands

# Default API runtime
cargo run --

# Explicit server subcommand
cargo run -- server

# Bundled daemon runtime
cargo run -p athena-daemon --bin athena_daemon

# Dedicated runtimes
cargo run -p athena-daemon --bin athena_clone_worker
cargo run -p athena-daemon --bin athena_backup_worker
cargo run -p athena-daemon --bin athena_deferred_query_worker
cargo run -p athena-daemon --bin athena_typesense_worker
cargo run -p athena-daemon --bin athena_daemon_legacy_workers

For a full API and daemon split, set daemon.enabled: true first. For a clone-only hybrid deployment, daemon.enabled can remain false.