Configuration

The daemon reads configuration from CLI flags and environment variables. CLI flags take precedence over env vars. Every flag has both a long form (--token) and a =-suffixed form (--token=evxd_…).

Required

`EVOXIV_DAEMON_TOKEN` / `--token` / `-t`

The token minted from the workspace's Start the daemon step (or later from Settings → Daemon tokens). At least 10 characters. The daemon refuses to start without it.

evoxiv-daemon --token 'evxd_AbC123...'
EVOXIV_DAEMON_TOKEN=evxd_… evoxiv-daemon

Connection

`EVOXIV_API_URL` / `--api-url`

The control plane URL. Defaults to https://api.evoxiv.com. You only set this when pointing at a self-hosted control plane or a staging environment.

evoxiv-daemon --api-url https://api.staging.evoxiv.com -t evxd_…

Workspaces

`EVOXIV_WORKSPACES_DIR` / `--workspaces-dir`

Root directory under which the daemon creates per-Story workdirs. Layout for each task:

<workspaces-dir>/<workspaceId>/<shortStoryId>/
  workdir/   # git clone of the Product repo
  logs/      # stdout/stderr of the backend run
  output/    # structured output captured for the memory continuation pass

Defaults to a sensible OS-specific cache directory. Override when you want the workdirs on a different volume (e.g. faster SSD, or a tmpfs for ephemeral runs).

Backend selection

`EVOXIV_DAEMON_BACKEND` / `--backend`

Which backends this daemon advertises as runtimes. One of:

auto (default) — every real backend present in the registry (codex, claude). dry-run is never auto-advertised.
<name> — pin to a single backend: codex, claude, or dry-run.

dry-run is a no-op backend used for smoke tests; it must be requested explicitly so a production daemon doesn't accidentally advertise a test stub.

`EVOXIV_DAEMON_NAME` / `--name`

Human-readable display name shown in the workspace's runtime list. Defaults to the host's OS release string + hostname.

Tuning

These are all optional, sensible defaults, almost never need touching.

`EVOXIV_DAEMON_POLL_MS`

How often the daemon polls task_queue for new work. Defaults to 2000 (2 seconds). Lower values reduce dispatch latency at the cost of more DB reads; higher values are fine for hosts processing batch work.

`EVOXIV_DAEMON_LEASE_SECONDS`

How long a leased task is held by this daemon before another daemon can steal it. Defaults to 900 (15 minutes). Raise this if your typical agent run is longer; lower it if you want faster failover when a daemon crashes mid-run.

`EVOXIV_DAEMON_HEARTBEAT_MS`

How often the daemon pings the control plane to report itself online. Defaults to 15_000 (15 seconds). Missed heartbeats flip the runtime to offline in the web app.

`EVOXIV_DAEMON_SKILL_SCAN_MS`

How often the daemon walks its skill roots and re-hashes SKILL.mds. Defaults to 60_000 (60 seconds). Decoupled from the heartbeat so a multi-backend host scans once for all backends collectively rather than once per backend.

Examples

The minimal production invocation, talking to evoxiv's hosted control plane:

evoxiv-daemon --token 'evxd_AbC123...'

Same, but pinned to a single backend:

evoxiv-daemon --token 'evxd_…' --backend claude

Self-hosted control plane, custom workdir, named for the host pool:

EVOXIV_API_URL=https://api.evoxiv.internal \
EVOXIV_DAEMON_TOKEN=evxd_… \
EVOXIV_WORKSPACES_DIR=/var/cache/evoxiv \
EVOXIV_DAEMON_NAME=pool-eu-1 \
  evoxiv-daemon

Run under a process supervisor (systemd, launchd, supervisord) for production. The daemon installs SIGINT/SIGTERM/SIGHUP handlers that drain the currently leased task (up to its lease) before exiting, so a clean stop doesn't leave a half-finished run.

On this page