Configuration

This document covers configuration 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

PILOT_SOCKET: Path to the daemon IPC socket (Default: /tmp/pilot.sock)
PILOT_REGISTRY: Registry server address (Default: 34.71.57.205:9000)
PILOT_HOSTNAME: Hostname to set during install; if unset, no hostname is registered (Default: (none))
PILOT_ADMIN_TOKEN: Admin token for enterprise operations (Default: (none))

Directory structure

~/.pilot/
  bin/                # Installed binaries (daemon, pilotctl, gateway, updater)
  bin/.pilot-version  # Current version (used by auto-updater)
  config.json         # Configuration file
  identity.json       # Ed25519 keypair (persistent identity)
  trust.json          # Trust state (trusted peers, pending requests)
  setups/             # Setup manifests (role identity files)
  received/           # Files received via data exchange
  inbox/              # Messages received via data exchange
  tasks/              # Task files and results
  pilot.pid           # Daemon PID file
  pilot.log           # Daemon log file
  updater.log         # Auto-updater log file

Daemon flags

--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
--admin-token <token>: Admin token for enterprise operations
--networks <ids>: Comma-separated network IDs to auto-join on startup

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

Setup manifests

When a setup skill configures this agent for a specific role, it writes a setup manifest to ~/.pilot/setups/<slug>.json. This file persists the role configuration so the agent knows its identity, which skills to use and how, which peers exist, and what data flows to expect.

{
  "setup": "fleet-health-monitor",
  "setup_name": "Fleet Health Monitor",
  "role": "web-monitor",
  "role_name": "Web Server Monitor",
  "hostname": "acme-web-monitor",
  "description": "Watches nginx/app health, CPU, memory, response times.",
  "skills": {
    "pilot-health": "Check nginx, app endpoints, SSL certs.",
    "pilot-alert": "Publish alerts to acme-alert-hub on health-alert.",
    "pilot-metrics": "Collect CPU, memory, disk, response time."
  },
  "peers": [
    {
      "role": "alert-hub",
      "hostname": "acme-alert-hub",
      "description": "Central alert aggregator"
    }
  ],
  "data_flows": [
    {
      "direction": "send",
      "peer": "acme-alert-hub",
      "port": 1002,
      "topic": "health-alert",
      "description": "Health check failures"
    }
  ],
  "handshakes_needed": ["acme-alert-hub"]
}

Manifest fields

setup (string): Setup slug (matches the filename)
setup_name (string): Human-readable setup name
role (string): This agent's role ID within the setup
role_name (string): Human-readable role name
hostname (string): This agent's hostname
description (string): What this agent does in context
skills (map): Skill name → contextual description of what it does in this role
peers (array): All peer agents in the setup (even indirect ones)
data_flows (array): Directional data flows (send/receive) with port and topic
handshakes_needed (array): Hostnames of peers that need direct trust (handshakes)

The manifest is a convention - the AI agent writes it during setup and reads it when it needs to act. No daemon or CLI changes are required.