Production Checklist

Use this checklist before running Compozy as a persistent daemon for real work. It is written for local or self-managed production-like environments where one service user owns one COMPOZY_HOME.

1. Pin the daemon identity and home

Check	Pass condition
Service user	A dedicated OS user owns the daemon process.
Home directory	`COMPOZY_HOME` is explicit, stable, and owned by the service user.
CLI operations	Operators use the same `COMPOZY_HOME` when running `compozy status`, `compozy session list`, and related commands.
File permissions	The home directory is not world-writable; socket access is limited to the daemon user.

Example:

sudo install -d -o compozy -g compozy -m 0750 /var/lib/compozy

Compozy creates its standard subdirectories with normal directory permissions, and the live UDS socket is chmodded to 0600.

2. Harden configuration

Review the home config that the daemon loads:

export COMPOZY_HOME="${COMPOZY_HOME:-$HOME/.compozy}"
sed -n '1,220p' "$COMPOZY_HOME/config.toml"

After changing it, run compozy daemon start --foreground during a maintenance window or in a staging COMPOZY_HOME to surface config validation errors directly.

Use explicit daemon and HTTP settings:

[daemon]
socket = "/var/lib/compozy/daemon.sock"

[http]
host = "localhost"
port = 2123

[log]
level = "info"
max_size_mb = 10
max_backups = 5
max_age_days = 30
compress_backups = false

[limits]
max_concurrent_agents = 20

Check	Pass condition
HTTP bind	`[http].host` is `localhost` unless Compozy is intentionally protected by a reverse proxy or host firewall.
UDS path	`[daemon].socket` is inside a directory owned by the daemon user.
Log level	`[log].level` is `info` or `warn` for unattended operation; use `debug` only for short investigations.
Limits	Agent concurrency limits and host resource expectations match the host capacity.
Provider auth	Native CLI providers are logged in for the service user, and `bound_secret` providers have resolvable `env:` or `vault:` credentials.

3. Run under a service manager

The service manager should:

start compozy daemon start --foreground
send SIGTERM during stop
restart on unexpected failure
provide the provider environment used by bound_secret providers and run under the user whose native provider logins should be visible
keep stdout and stderr in a known log location

For concrete service files, see Daemon Operations.

Compozy writes structured logs to $COMPOZY_HOME/logs/compozy.log. Detached daemon startup also appends child stdout and stderr there. The daemon rotates this file directly from the LogSink configured under [log]; no external logrotate rule is required for the default file.

[log]
level = "info"
max_size_mb = 10
max_backups = 5
max_age_days = 30
compress_backups = false

Check	Pass condition
Retention	`max_size_mb * (max_backups + 1)` fits the filesystem budget for the Compozy home.
Access	Only operators who need runtime logs can read `$COMPOZY_HOME/logs/` and downloaded support bundles.
Error review	Recent `error` lines are reviewed during incident response and before upgrades.

5. Monitor daemon and runtime health

Use both runtime status and doctor diagnostics:

compozy status --output json
compozy doctor --output json

If HTTP is available locally:

curl -fsS http://localhost:2123/api/status >/dev/null
curl -fsS http://localhost:2123/api/doctor >/dev/null

Alert on:

Signal	Failing condition
Daemon status	Status is not `running`, or PID is absent.
HTTP status	`/api/status` or `/api/doctor` cannot be reached from the host.
Active sessions	Count exceeds the expected operating range.
Database size	`global_db_size_bytes` or `session_db_size_bytes` grows faster than planned.
Logs	Repeated startup, socket, database, or ACP spawn errors.

6. Back up state

Back up at least:

$COMPOZY_HOME/compozy.db and SQLite sidecars
$COMPOZY_HOME/sessions/
$COMPOZY_HOME/config.toml
$COMPOZY_HOME/agents/
$COMPOZY_HOME/skills/
$COMPOZY_HOME/memory/

Use one of the backup paths in Database Operations. For unattended hosts, prefer a scheduled cold backup when the daemon can be stopped. If it cannot be stopped, use SQLite .backup instead of copying only the main database files.

Check	Pass condition
Frequency	Backup frequency matches the amount of session history you can afford to lose.
Coverage	Backups include global and per-session databases plus config and content directories.
Restore drill	A restore has been tested on a separate `COMPOZY_HOME`.
Retention	Old backups expire according to your storage and compliance needs.

7. Reserve host resources

Compozy starts real ACP-compatible agent CLIs as child processes. Size the host for the agent binaries you run, not only the daemon.

Check	Pass condition
Disk	`COMPOZY_HOME`, logs, and session event databases have room to grow.
File descriptors	The service limit is high enough for concurrent sessions, sockets, logs, and SQLite handles.
Process count	The service user can run the daemon plus expected agent child processes.
PATH	Provider commands such as `npx`, `codex`, or `gemini` are available to the service environment.
Shutdown	The service manager gives Compozy time to stop sessions and close databases before killing it.

For systemd, set resource limits in the service file when needed:

[Service]
LimitNOFILE=8192
TimeoutStopSec=30
Restart=on-failure

8. Upgrade deliberately

Use this flow for binary upgrades:

export COMPOZY_HOME=/var/lib/compozy

compozy status
compozy daemon stop

# Back up COMPOZY_HOME here.
# Install the new compozy binary here.

compozy daemon start
compozy status
compozy doctor

Do not rely on old daemon state after replacing the binary. Stop, back up, replace, start, and then confirm status and health.

Final readiness gate

Area	Ready when
Daemon lifecycle	`compozy daemon start`, `compozy status`, and `compozy daemon stop` work under the service manager.
Socket	The CLI can reach the configured UDS socket as the intended operator user.
HTTP	HTTP is bound only where intended and health endpoints are reachable.
Logs	Logs rotate and recent errors are actionable.
Databases	Backups include `compozy.db`, per-session `events.db` files, metadata, and sidecars.
Sessions	Test session creation, stop, list, and resume work with the production service environment.
Recovery	Operators know how to restore a backup into a separate `COMPOZY_HOME` before touching production state.

Daemon Operations shows service manager setup.
Database Operations gives backup and inspection commands.
Troubleshooting maps common failures to fixes.