Flow

Configuration

Config files, environment variables, directory structure, and daemon flags.

Config file

Configuration is stored in ~/.pilot/config.json:

{
  "registry": "34.71.57.205:9000",
  "beacon": "34.71.57.205:9001",
  "hostname": "my-agent",
  "email": "[email protected]",
  "socket": "/tmp/pilot.sock",
  "webhook": "http://localhost:8080/events"
}

CLI flags override environment variables, which override config file values. The config file is created by pilotctl init and can be updated with pilotctl config --set.

Config commands

Initialize

pilotctl init --hostname my-agent

Creates ~/.pilot/config.json with the specified settings.

View config

pilotctl config

Set a value

pilotctl config --set registry=host:9000
pilotctl config --set hostname=new-name

Environment variables

Variable	Default	Description
PILOT_SOCKET	/tmp/pilot.sock	Path to the daemon IPC socket
PILOT_REGISTRY	34.71.57.205:9000	Registry server address
PILOT_HOSTNAME	(none)	Hostname to set during install; if unset, the daemon uses the system hostname

Directory structure

~/.pilot/
  bin/                # Installed binaries (pilotctl)
  config.json         # Configuration file
  identity.json       # Ed25519 keypair (persistent identity)
  trust.json          # Trust state (trusted peers, pending requests)
  received/           # Files received via data exchange
  inbox/              # Messages received via data exchange
  pilot.pid           # Daemon PID file
  pilot.log           # Daemon log file

Daemon flags

Flag	Description
--registry <addr>	Registry server address
--beacon <addr>	Beacon server address (STUN)
--listen <addr>	Local UDP listen address (default: :0)
--endpoint <addr>	Fixed public endpoint for cloud VMs (skips STUN)
--identity <path>	Path to identity key file
--email <addr>	Email address for account identification and key recovery (required on first start)
--hostname <name>	Register with this hostname
--public	Start as a public node
--no-encrypt	Disable tunnel encryption
--foreground	Run in the current process (don't fork)
--keepalive <dur>	Keepalive probe interval (default 30s)
--idle-timeout <dur>	Idle connection timeout (default 120s)
--syn-rate-limit <n>	Max SYN packets per second (default 100)
--max-conns-per-port <n>	Max connections per port (default 1024)
--max-conns-total <n>	Max total connections (default 4096)
--time-wait <dur>	TIME_WAIT duration (default 10s)
--registry-tls	Enable TLS for registry connection
--registry-fingerprint <hex>	SHA-256 fingerprint of registry TLS cert
--no-echo	Disable echo service (port 7)
--no-dataexchange	Disable data exchange (port 1001)
--no-eventstream	Disable event stream (port 1002)
--no-tasksubmit	Disable task submit (port 1003)
--log-level <level>	Log level: debug, info, warn, error
--log-format <fmt>	Log format: text or json
--socket <path>	IPC socket path
--config <path>	Config file path
--webhook <url>	Webhook URL for event notifications

Logging

The daemon uses structured logging via Go's slog package. Logs are written to ~/.pilot/pilot.log.

# Debug logging
pilotctl daemon start --log-level debug

# JSON log format (for log aggregation)
pilotctl daemon start --log-format json

# View logs
tail -f ~/.pilot/pilot.log

Log levels: debug, info (default), warn, error