Configure the Watchflare Agent

The agent is configured via a TOML file written at registration. You rarely need to edit it manually — most fields are set by the register command. The file is reloaded on service restart.

| Platform | Path | |----------|------| | Linux | /etc/watchflare/agent.conf | | macOS (Apple Silicon) | /opt/homebrew/etc/watchflare/agent.conf | | macOS (Intel) | /usr/local/etc/watchflare/agent.conf |

Full example

# Hub connection
server_host = "hub.example.com"
server_port = "50051"

# Credentials (written at registration — do not edit manually)
agent_id  = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
agent_key = "base64encodedkey..."

# TLS
ca_cert_file = "/etc/watchflare/ca.pem"
server_name  = "watchflare"

# Collection intervals
heartbeat_interval = 5    # seconds
metrics_interval   = 30   # seconds

# Write-Ahead Log
wal_enabled    = true
wal_path       = "/var/lib/watchflare/metrics.wal"
wal_max_size_mb = 10

# Logging
log_file  = "/var/log/watchflare-agent.log"
log_level = "info"

# Container metrics (opt-in)
container_metrics = false

Fields

Connection

| Field | Type | Default | Description | |-------|------|---------|-------------| | server_host | string | — | Hub hostname or IP address | | server_port | string | "50051" | Hub gRPC port |

Credentials

These fields are written automatically by register. Do not edit them.

| Field | Type | Description | |-------|------|-------------| | agent_id | string | UUID assigned by the Hub at registration | | agent_key | string | HMAC key used to sign gRPC requests |

TLS

| Field | Type | Default | Description | |-------|------|---------|-------------| | ca_cert_file | string | — | Path to the Hub's CA certificate, written at registration | | server_name | string | "watchflare" | Server name for TLS certificate validation. Written at registration from the Hub response. Must match the certificate CN. |

Collection intervals

| Field | Type | Default | Description | |-------|------|---------|-------------| | heartbeat_interval | int | 5 | Seconds between heartbeat pings | | metrics_interval | int | 30 | Seconds between metrics collection and send |

Write-Ahead Log

| Field | Type | Default | Description | |-------|------|---------|-------------| | wal_enabled | bool | true | Enable local buffering of metrics when the Hub is unreachable | | wal_path | string | {data_dir}/metrics.wal | WAL file path | | wal_max_size_mb | int | 10 | Maximum WAL size in MB. Older records are dropped (FIFO) when the limit is reached. |

Logging

| Field | Type | Default | Description | |-------|------|---------|-------------| | log_file | string | "" | Log file path. Empty means stdout (captured by the service manager). | | log_level | string | "info" | Log verbosity: debug, info, warn, error. Override at runtime with WATCHFLARE_DEBUG=1. |

Container metrics

| Field | Type | Default | Description | |-------|------|---------|-------------| | container_metrics | bool | false | Enable per-container metrics (Docker and Podman). On Linux, requires the watchflare user to be in the docker group. See Docker container metrics. |

Environment variables

Four environment variables can override default paths and behavior. They are used internally by the Homebrew service wrapper on macOS and generally do not need to be set manually.

| Variable | Description | |----------|-------------| | WATCHFLARE_CONFIG_DIR | Override the config directory (/etc/watchflare on Linux) | | WATCHFLARE_DATA_DIR | Override the data directory (/var/lib/watchflare on Linux) | | WATCHFLARE_LOG_FILE | Override the log file path | | WATCHFLARE_DEBUG | Set to 1 to force debug log level, regardless of log_level |

File locations

Linux

| Path | Purpose | Owner | Mode | |------|---------|-------|------| | /usr/local/bin/watchflare-agent | Binary | root:root | 755 | | /etc/watchflare/agent.conf | Config | root:watchflare | 640 | | /etc/watchflare/ca.pem | CA certificate | root:watchflare | 640 | | /var/lib/watchflare/ | Data directory | watchflare:watchflare | 750 | | /var/lib/watchflare/metrics.wal | WAL | watchflare:watchflare | — | | /var/lib/watchflare/packages.state.json | Package state | watchflare:watchflare | 640 | | /var/log/watchflare-agent.log | Logs | watchflare:watchflare | 644 | | /etc/systemd/system/watchflare-agent.service | Service | root:root | 644 |

macOS

$(brew --prefix) is /opt/homebrew on Apple Silicon and /usr/local on Intel.

| Path | Purpose | |------|---------| | $(brew --prefix)/bin/watchflare-agent | Binary | | $(brew --prefix)/etc/watchflare/agent.conf | Config | | $(brew --prefix)/etc/watchflare/ca.pem | CA certificate | | $(brew --prefix)/var/watchflare/ | Data directory | | $(brew --prefix)/var/watchflare/metrics.wal | WAL | | $(brew --prefix)/var/watchflare/packages.state.json | Package state | | $(brew --prefix)/var/log/watchflare-agent.log | Logs |