The Pharos ecosystem is designed to be highly configurable via environment variables, ensuring compatibility across Home Lab, Enterprise, and Sandbox environments.
🖥️ Server Configuration (pharos-server)
| Variable | Description | Default | Impact |
|---|---|---|---|
PHAROS_ADDR | The IP and port the server binds to. | 0.0.0.0:2378 | Network accessibility. |
PHAROS_TLS_CERT | (Mandatory) Path to the SSL/TLS certificate. | None | Security (SSL). |
PHAROS_TLS_KEY | (Mandatory) Path to the SSL/TLS private key. | None | Security (SSL). |
PHAROS_STORAGE_PATH | Path to the JSON file for persistent storage. | Unset (Memory) | Data persistence. |
PHAROS_KEYS_DIR | Directory containing authorized SSH public keys. | ./keys | Authorization. |
PHAROS_SECURITY_TIER | Security mode: open, protected, or scoped. | open | Access control. |
PHAROS_SYNC_ADDR | The public address used for peer registration. | Unset | Multi-server sync. |
PHAROS_BOOTSTRAP_PEER | Address of a peer to pull initial data from. | Unset | Multi-server sync. |
PHAROS_LDAP_URL | URL of the LDAP server for Enterprise tier. | Unset | External Auth. |
PHAROS_CPU_THRESHOLD | CPU usage percentage for health alerts. | 90.0 | Monitoring. |
PHAROS_MEM_THRESHOLD_GB | Memory usage (GB) for health alerts. | 1 | Monitoring. |
PHAROS_PRESENCE_ALERT_THRESHOLD_SECONDS | Seconds a machine can go without a heartbeat before triggering a presence alert. | 7200 | Monitoring. |
PHAROS_ALERT_WEBHOOK_URL | URL to POST a JSON payload to when a machine’s presence alert fires. Optional - feature is inactive if unset. | Unset | Monitoring. |
PHAROS_ALERT_SCRIPT | Local script/binary path to execute (with hostname and last-seen timestamp as arguments) when a machine’s presence alert fires. Optional - feature is inactive if unset. | Unset | Monitoring. |
PHAROS_WEBHOOK_URL | URL to POST a JSON notification to on every successful add/change/delete. Optional - feature is inactive if unset. Distinct from PHAROS_ALERT_WEBHOOK_URL (presence-alert webhook, which only fires on node staleness) - configure independently. Note: fires on every heartbeat add from pharos-pulse too, which may be noisy. | Unset | Monitoring. |
PHAROS_WEBHOOK_FORMAT | Payload format for PHAROS_WEBHOOK_URL: generic (default, custom-REST-API JSON), slack (Slack incoming-webhook compatible), or discord (Discord webhook compatible). | generic | Monitoring. |
RUST_LOG | Log verbosity (error/warn/info/debug/trace, optionally per-module e.g. pharos_server=debug). Standard Rust ecosystem convention, intentionally not PHAROS_-prefixed. A value that doesn’t match any known module (including plain typos) silently disables all output with no warning — if logs go quiet after setting this, check for typos first. | info | Observability. |
Webhook Payload Examples
PHAROS_ALERT_WEBHOOK_URL — Dead Man’s Switch, fires once when a node goes stale:
{
"event": "node_down",
"hostname": "srv-db-01",
"last_seen_at": "2026-08-08T04:12:00Z",
"elapsed_seconds": 7530
}PHAROS_WEBHOOK_URL with PHAROS_WEBHOOK_FORMAT=generic (the default) — fires on every add/change/delete:
{
"event": "add",
"timestamp": "2026-08-08T04:12:00Z",
"fields": { "hostname": "srv-db-01", "ip_addr": "10.0.0.6" }
}PHAROS_WEBHOOK_FORMAT=slack or =discord send a single human-readable summary line instead of structured fields — a Slack incoming-webhook-compatible {"text": "..."}, or a Discord-compatible {"content": "..."}:
{ "text": "Pharos: record added/updated (hostname=srv-db-01, ip_addr=10.0.0.6)" }PHAROS_ALERT_SCRIPT is invoked directly (never through a shell) as your-script.sh <hostname> <last_seen_at> — write it to expect exactly those two positional arguments.
🛠️ CLI Client Configuration (ph, mdb)
Both clients resolve the server address in this order: PHAROS_SERVER env var → PHAROS_HOST/PHAROS_PORT env vars → /etc/pharos/client.conf (a plain PHAROS_SERVER=host:port line, written automatically by the Automated Installation Guide’s node/pulse targets so managed machines don’t need the env var set by hand) → the built-in default (127.0.0.1:2378). Run either client with --debug to see which of these four sources it actually resolved against — see CLI Clients.
| Variable | Description | Default | Impact |
|---|---|---|---|
PHAROS_HOST | Hostname or IP of the Pharos server. | 127.0.0.1 | Connectivity. |
PHAROS_PORT | TCP port of the Pharos server. | 2378 | Connectivity. |
PHAROS_SERVER | Combined address (host:port). | Unset | Connectivity. |
PHAROS_CA_CERT | Path to CA certificate for TLS trust. | Unset | Security. |
PHAROS_PRIVATE_KEY | Path to SSH private key for authentication. | ~/.ssh/id_ed25519 | Authorization. |
💓 Pulse Agent Configuration (pharos-pulse)
| Variable | Description | Default | Impact |
|---|---|---|---|
PHAROS_SERVER | Address of the Pharos server. | 127.0.0.1:2378 | Connectivity. |
PHAROS_MACHINE_NAME | Override hostname for node registration. | System Hostname | Identity. |
PHAROS_CA_CERT | Path to CA certificate for TLS trust. | Unset | Security. |
PHAROS_PRIVATE_KEY | Path to SSH private key for authentication. | Unset | Authorization. |
🌐 Web Console Configuration (pharos-console-web)
| Variable | Description | Default | Impact |
|---|---|---|---|
PHAROS_HOST | Hostname or IP of the backend Pharos server. | 127.0.0.1 | Backend connectivity. |
PHAROS_CA_CERT | Path to CA certificate for trusting the backend’s TLS. | Unset | Security. |
PHAROS_SANDBOX | Forces the console’s backend connection to use TLS, and enables Sandbox-specific UI hints. Requires PHAROS_CA_CERT to also be set - the console refuses to start a TLS connection otherwise, rather than silently disabling certificate verification. | false | Security, UX/UI. |
PHAROS_TLS_CERT | Path to SSL/TLS certificate for Web. | Unset | Security (HTTPS). |
PHAROS_TLS_KEY | Path to SSL/TLS private key for Web. | Unset | Security (HTTPS). |
PHAROS_PRIVATE_KEY | Private key for signing auth challenges. | Unset | Authorization. |
PHAROS_PUBLIC_KEY | Public key associated with the private key. | Unset | Authorization. |
PHAROS_SKIP_AUTH | Testing only - never set in a real deployment. Bypasses login entirely, granting a synthesized admin session to any request. Only takes effect in a build explicitly compiled with ALLOW_SKIP_AUTH=true npm run build (see pharos-console-web/src/middleware.ts) - the real published image (what install.sh hub and the Sandbox deployment both use) does not include this bypass at all, regardless of this variable’s runtime value. | Unset | Security (testing only). |