Configuration and COVEN_HOME

Daemon configuration reference for COVEN_HOME, local IPC, coven.sqlite3, daemon.json, privacy, and retention.

Coven's daemon configuration surface is deliberately small. The important knob is COVEN_HOME, the state directory that contains the local socket, ledger, event log, and daemon metadata.

Default layout

If COVEN_HOME is not set, Coven uses:

$HOME/.coven

The daemon uses this layout:

Path	Purpose
`$COVEN_HOME/coven.sock`	Unix socket for same-user local API access on Unix-like hosts.
Daemon-reported named pipe	Owner-only local IPC endpoint on Windows.
`$COVEN_HOME/coven.sqlite3`	SQLite ledger for sessions and append-only events.
`$COVEN_HOME/daemon.json`	Daemon metadata such as pid, start time, and socket path.
`$COVEN_HOME/daemon.lock`	Lifecycle lock (advisory `flock`) that serializes `daemon start`/`stop`/`restart` orchestration so concurrent lifecycle commands cannot race.
`$COVEN_HOME/daemon-serve.lock`	Serve lock held for the whole life of a `daemon serve` process, guaranteeing at most one daemon writes a given SQLite store.
`$COVEN_HOME/daemon-recovery.log`	Append-only, timestamped log of lifecycle and recovery events: startups, terminated duplicate daemons, accept-loop errors, API handler errors, and panics.
`$COVEN_HOME/privacy.toml`	Optional log-redaction, raw-artifact, and retention settings.
`$COVEN_HOME/keys/session-artifacts.key`	Local encryption key created only when raw artifact persistence is enabled.

Do not commit this directory. It can contain prompts, model output, local paths, and operational metadata.

Relocate daemon state

Set COVEN_HOME before starting or restarting the daemon:

export COVEN_HOME="$HOME/.local/share/coven"
coven daemon restart

After restart, confirm the selected socket and API contract:

coven daemon status

On Unix-like hosts, scripts that call the socket should derive the socket path from the same environment:

curl --unix-socket "$COVEN_HOME/coven.sock" \
  http://localhost/api/v1/health

Privacy and retention

Session event payloads are redacted before broad API and log responses. Raw artifact persistence is disabled by default.

Optional $COVEN_HOME/privacy.toml:

persist_raw_artifacts = false
raw_artifact_retention_days = 7
log_retention_days = 30
extra_patterns = ["custom-sensitive-[0-9]+"]

Environment variables override the matching file values:

Name	Scope
`COVEN_PERSIST_RAW_ARTIFACTS`	Enables encrypted raw artifact persistence when truthy.
`COVEN_RAW_ARTIFACT_RETENTION_DAYS`	Sets raw artifact retention; positive whole days only.
`COVEN_LOG_RETENTION_DAYS`	Sets redacted event-log retention; positive whole days only.

The CLI also parses covenCli.privacy from ~/.config/coven/settings.json. Those values currently participate in maintenance, storage-health, and manual prune calculations. Event redaction, raw artifact creation, and raw artifact retrieval still use privacy.toml plus the environment overrides above, so use those surfaces for security-sensitive behavior.

Prune retained data with:

coven logs prune --dry-run
coven logs prune

Current supported knobs

Supported today:

Name	Scope
`COVEN_HOME`	Moves daemon state, local IPC, ledger, and metadata.
`$COVEN_HOME/privacy.toml`	Controls redaction patterns, raw artifact persistence, and retention.
`COVEN_PERSIST_RAW_ARTIFACTS`	Overrides the raw artifact persistence setting.
`COVEN_RAW_ARTIFACT_RETENTION_DAYS`	Overrides raw artifact retention.
`COVEN_LOG_RETENTION_DAYS`	Overrides redacted event retention.

Not supported as daemon configuration yet:

Name	Current posture
`coven.toml`	Do not rely on it for daemon startup behavior.
`COVEN_SOCKET`	The socket path is derived from `COVEN_HOME`.
`COVEN_LOG_LEVEL`	Not a stable daemon configuration contract.
`COVEN_DAEMON_FOREGROUND`	Not a stable daemon configuration contract.

Those names may appear in future design discussions, but clients and operators should not depend on them until the Rust daemon documents support.

File permissions

The local trust boundary depends on permissions around $COVEN_HOME and the active local IPC endpoint. The daemon should keep state private to the owning user. Anyone who can connect to the Unix socket or Windows named pipe can act as a local Coven client.