[ Switch to styled version → ]

← Docs index

Configuration

This document describes 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": "user@example.com",
  "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_BEACON: Beacon server address (used for STUN, NAT punch, and relay). Default: 34.71.57.205:9001.
• PILOT_DAEMON_BIN: Override path to the pilot-daemon binary. Default: auto-discovered.
• PILOT_GATEWAY_BIN: Override path to the pilot-gateway binary. Default: auto-discovered.
• PILOT_HOSTNAME: Hostname to set during install. If unset, the node is assigned an internal hostname of the form pilot-XXXXXXXX. Default: none.
• PILOT_ADMIN_TOKEN: Admin token for enterprise operations. Default: none.
• PILOT_HOME: Directory where pilot stores identity, config, and received files. Default: ~/.pilot.
• PILOT_EMAIL: Email address used for first-time daemon registration. Default: none.
• PILOT_RC: Path to a shell RC snippet sourced by the daemon on startup. Default: none.

Directory structure

~/.pilot/
  bin/                # Installed binaries (pilot-daemon, pilotctl, pilot-gateway, pilot-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
  pilot.pid           # Daemon PID file
  pilot.log           # Daemon log file
  updater.log         # Auto-updater log file

Daemon flags

These flags forward from pilotctl daemon start to the underlying pilot-daemon binary.

• --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
• --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)
• --trust-auto-approve: Auto-approve every incoming trust handshake
• --log-level <level>: Log level: debug, info, warn, error
• --log-format <fmt>: Log format: text or json
• --socket <path>: IPC socket path (default /tmp/pilot.sock)
• --config <path>: Config file path
• --webhook <url>: Webhook URL for event notifications
• --admin-token <token>: Admin token for network create/admin operations
• --networks <ids>: Comma-separated network IDs to auto-join on startup
• --wait <dur>: How long to wait for the daemon to become ready (default 15s)

pilot-daemon-only tuning flags

The following flags are consumed only when invoking the pilot-daemon binary directly. They are not forwarded by pilotctl daemon start.

• -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. Default: false.
• -registry-fingerprint <hex>: SHA-256 fingerprint of registry TLS cert. Default: none.
• -no-echo: Disable the built-in echo service (port 7). Default: false.
• -no-dataexchange: Disable the built-in data exchange (port 1001). Default: false.
• -dataexchange-b64: Include a lossless data_b64 field alongside data in inbox messages. Default: false.
• -no-eventstream: Disable the built-in event stream (port 1002). Default: false.
• -relay-only: Hide real_addr from peers; reach only via beacon-relay. Default: false.
• -transport <mode>: Tunnel transport — `udp` (default, today's behavior) or `compat` (opt-in, tunnels Pilot packets over WSS to the beacon for daemons in UDP-blocked environments). See "Running pilot behind a firewall".
• -compat-beacon <url>: WSS endpoint used when -transport=compat. Default: wss://beacon.pilotprotocol.network/v1/compat
• -tls-trust <mode>: Compat-mode TLS trust — `system` (default; OS trust store, matches the public beacon's Let's Encrypt cert) or `pinned` (Pilot CA root embedded in the daemon binary). Default will flip back to `pinned` in a future release once the production Pilot root ships embedded.
• -fake-listen-addr <addr>: Advertise this listen_addr to the registry instead of the real one. Default: none.

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 an agent for a role, it writes a setup manifest to ~/.pilot/setups/<slug>.json. This file persists the role configuration.

{
  "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 to 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.