Agent configuration reference

The Arctic agent is configured entirely through environment variables; it has no configuration file of its own. Set them as Environment= lines in the agent's systemd unit (then systemctl daemon-reload && systemctl restart arctic), or in the shell for a foreground run.

This page covers the agent-side variables only. The CLI's ARCTIC_* variables (ARCTIC_CONFIG, ARCTIC_CLIENT_ID, ARCTIC_KNOWN_HOSTS, and friends) are documented in the CLI reference.

Booleans accept true/false (also 1/0). Intervals ending in _SECONDS are plain integers; RECOVERY_TOKEN_TTL is a Go duration string (24h, 90m). A value that fails to parse silently falls back to the default.

Summary

Core

DATA_DIR

Default: /opt/tillered

The agent's data directory. Holds the SQLite database (arctic.db and its WAL/SHM sidecars, enforced to mode 0600), the peer's Ed25519 identity key (peer.key), and the backup/ directory of database snapshots. Backing up a peer means capturing peer.key plus a database snapshot from this directory; see Backup and restore.

ENV

Default: prod

Environment name. The default prod omits source-file locations from log output; any other value includes them, which is useful in development.

LOG_LEVEL

Default: info

Log verbosity for the agent's structured logs. See Monitoring for what the agent logs at each level and how to ship the audit events.

LOG_FORMAT

Default: json

Log output format. The default json emits structured lines suitable for journald pipelines and SIEMs; see Monitoring.

API_PORT

Default: 8080

The port the agent's HTTP API listens on. Serves both the operator REST API and the peer-to-peer cluster API, over TLS by default as of v1.4.2 (see PEER_TLS_ENABLED).

TLS

PEER_TLS_ENABLED

Default: true

Wraps the agent's HTTP surface in TLS 1.3 and pins every agent-to-agent dial to the peer's Ed25519 identity key. This also serves the operator REST API over TLS, with an in-memory self-signed certificate derived from peer.key (no CA, no issuance). The setting is cluster-wide: a dialing peer expects a TLS peer, so every agent in a cluster must agree.

Set to false to restore the prior plaintext HTTP behaviour, for example when a TLS-terminating proxy fronts the API. See TLS and trust.

API_TLS_CERT and API_TLS_KEY

Default: unset

Paths to a certificate and key file for the operator API, for deployments that want a CA-issued certificate instead of the self-signed identity certificate. Both must be set together. The file-certificate path is pinned to TLS 1.3 so it cannot be downgraded. See TLS and trust.

Security

RECOVERY_TOKEN_TTL

Default: 24h (Go duration string)

Lifetime and rotation interval of the break-glass recovery token at /etc/arctic/recovery.token. The agent rewrites the file with a fresh value every TTL, and a presented token older than the TTL is rejected even if the rotation loop has died. Read the file at time of use; a saved copy is dead after the next rotation or agent restart. If the file becomes unwritable, the old token ages out and recovery degrades to disabled rather than leaving a credential that outlives its lifetime. See Access recovery.

REVOCATION_CACHE_TTL

Default: 30 (seconds)

How long the bearer-auth path caches a credential-status verdict. This bounds how long a token keeps working after its issuing credential is revoked: revoked credentials see 401s within this window. Set to 0 to disable the cache so every request consults the store. See Credential management.

Database backups

DB_BACKUP_INTERVAL_SECONDS

Default: 86400 (one day)

How often the agent snapshots arctic.db into $DATA_DIR/backup/ using SQLite VACUUM INTO (safe while the agent is running). 0 or a negative value disables periodic snapshots; arctic database snapshot still captures one on demand either way. See Backup and restore.

DB_BACKUP_RETENTION

Default: 7 (clamped to at least 1)

How many database snapshots to keep before the oldest are pruned. See Backup and restore.

Cluster

CLUSTER_HEARTBEAT_INTERVAL_SECONDS

Default: 60

The cadence of the per-peer heartbeat that drives gossip and drift resolution. Each peer is keyed independently, so an unreachable peer backs off without affecting the others. See the clustering concept.

Egress proxy

HTTP_PROXY, HTTPS_PROXY, NO_PROXY

Default: unset

The agent honours the standard Unix proxy environment variables (upper- or lowercase) -- the same convention curl, wget, and most package managers follow -- for its outbound HTTP: peer-to-peer heartbeats, gossip, and voucher refresh all route through the configured proxy. With PEER_TLS_ENABLED=true (the default) peer traffic is HTTPS, so HTTPS_PROXY is the variable that applies; plaintext clusters use HTTP_PROXY.

On hosts behind a mandatory corporate egress proxy this breaks peer-to-peer traffic, because the proxy typically cannot reach (or refuses) the private addresses of the other peers. The fix is not to remove the proxy but to exempt peer traffic from it with NO_PROXY, which accepts hostnames, IPs, and CIDRs:

[Service]
Environment=NO_PROXY=10.0.0.0/8,192.168.0.0/16
Environment=no_proxy=10.0.0.0/8,192.168.0.0/16

Add this as a systemd drop-in (systemctl edit arctic) rather than editing the unit file, so it survives agent upgrades, then systemctl daemon-reload && systemctl restart arctic. Set both cases: the agent reads the lowercase form first, and host tooling may have set either. CIDR entries match only when the peer endpoint is an IP literal; DNS-named endpoints must be listed by name or domain suffix (.internal).

A systemd service does not inherit shell environment, so if the agent is seeing proxy variables they come from the systemd level (commonly DefaultEnvironment= in /etc/systemd/system.conf, pushed by configuration management). Inspect what the unit actually receives with systemctl show arctic -p Environment. To clear the proxy for the agent entirely instead of exempting peers, set the variables to empty in a drop-in (Environment=HTTP_PROXY= HTTPS_PROXY= http_proxy= https_proxy=); an empty value is treated as unset. Prefer the NO_PROXY form where the proxy exists for compliance reasons: it keeps genuine egress on the proxy and exempts only cluster traffic.

See Peers unreachable behind an egress proxy for the failure signature and diagnosis steps.