[ 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": "[email protected]",
  "socket": "$XDG_RUNTIME_DIR/pilot.sock (Linux, when set), else /tmp/pilot.sock",
  "webhook": "http://localhost:8080/events"
}

CLI flags take highest precedence. For `pilotctl daemon start`, the config file is consulted before environment variables. 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

Automatic updates

Pilot ships a `pilot-updater` sidecar that can keep binaries on the latest stable release. Automatic updates are off by default.

Check the status

pilotctl update status

Shows whether automatic updates are enabled and your current version.

Enable / disable

pilotctl update enable
pilotctl update disable

The setting is stored in `~/.pilot/auto-update.json` and is re-read by the updater on its next check. When enabled, the updater installs new stable releases on its periodic check after verifying release checksums.

Update once, manually

pilotctl update

Runs a single check-and-install. This works regardless of the automatic-update setting. Pin to a specific release with `--pin <version>`.

Environment variables

Directory structure

~/.pilot/
  bin/                # Installed binaries (pilot-daemon, pilotctl, pilot-updater; pilot-gateway if installed separately)
  bin/.pilot-version  # Current version (used by auto-updater)
  config.json         # Configuration file
  account.json        # Account identity (email supplied via --email / PILOT_EMAIL)
  auto-update.json    # Automatic-update opt-in state (pilotctl update enable/disable)
  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-<pid>.log     # Per-run daemon log files (one per daemon start)
  pilot.log           # Symlink to the current run's log file
  updater.log         # Auto-updater log file

Daemon flags

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

pilot-daemon-only tuning flags

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

Logging

The daemon uses structured logging via Go's `slog` package. Each run writes to a per-run log file `~/.pilot/pilot-<pid>.log`; `~/.pilot/pilot.log` is a symlink to the current run's 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

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.