Configuration

Configuration

All HomePilot configuration is via environment variables (prefix HP_) or a .env file. See Installation for the full reference table.

Zero-Secrets Deployment

HomePilot v2.2+ uses a zero-secrets .env file — no HomePilot secrets in the environment file. All sensitive values are stored in the age-encrypted vault and resolved at runtime.

Secret Resolution Order

env var → vault → file → auto-generate

HP_SECRET_KEY=          → vault("secret-key") → auto-generate & persist
HP_ADMIN_SECRET=         → vault("admin-secret") → ConfigError (production)
PVE_API_TOKEN=           → vault("pve-token") → unavailable
JUMPSERVER_AUTH_TOKEN=   → vault("jumpserver-token") → unavailable
HP_EVENTS_WEBHOOK_SECRET=→ vault("webhook-secret") → unavailable

The .env file only contains non-secret configuration: ports, URLs, feature flags, and service discovery addresses.

Minimum .env (no secrets)

HP_DAEMON_PORT=8000
HP_PROXMOX_HOST=pve.example.local
HP_PROXMOX_VERIFY_SSL=false

The Vault

The vault encrypts secrets using age encryption via the pyrage Python library — no system age binary required. The master identity is protected with AES-256-GCM derived from the vault passphrase.

Auto-Generated Passphrase (recommended)

If neither HP_VAULT_PASSPHRASE nor HP_VAULT_PASSPHRASE_FILE is set:

1. A 256-bit passphrase is auto-generated using secrets.token_urlsafe(32)
2. Persisted to {data_dir}/.vault_passphrase with mode 0o600
3. On subsequent starts, the persisted passphrase is loaded automatically

This is the recommended approach for Docker deployments. No manual passphrase management required.

Passphrase File (production, Docker Swarm)

For production deployments where you need to control the passphrase:

echo "my-strong-passphrase" > /etc/homepilot/vault_pass
chmod 600 /etc/homepilot/vault_pass

HP_VAULT_PASSPHRASE_FILE=/run/secrets/hp_vault_passphrase

Docker secrets:

secrets:
  hp_vault_passphrase:
    file: /etc/homepilot/vault_pass

services:
  backend:
    secrets:
      - hp_vault_passphrase
    environment:
      HP_VAULT_PASSPHRASE_FILE: /run/secrets/hp_vault_passphrase

_try_vault_secret — Multi-Key Extraction

When resolving a secret from the vault, the system tries multiple key names:

1. "value" → 2. "secret" → 3. "key" → 4. "token" → first value in dict

This accommodates different vault entry formats:

Vault Key	Common Value Keys	Example
secret-key	value, secret	{"value": "abc123..."}
admin-secret	value, secret	{"secret": "xyz789..."}
pve-token	token, key	{"token": "monitor@pam!api=uuid"}
jumpserver-token	value	{"value": "token_hex..."}
webhook-secret	value, secret	{"value": "webhook_hex..."}

Vault CLI

# Store a secret interactively
docker compose exec -it backend hp vault set <name>

# Retrieve (JSON output)
docker compose exec backend hp vault get <name>

# List all secret names
docker compose exec backend hp vault list

# Delete a secret
docker compose exec backend hp vault delete <name>

Bootstrap Workflow

# 1. Start the stack — passphrase auto-generates
docker compose up -d

# 2. Set vault secrets
docker compose exec -it backend hp vault set secret-key
docker compose exec -it backend hp vault set admin-secret
docker compose exec -it backend hp vault set webhook-secret
docker compose exec -it backend hp vault set jumpserver-token
docker compose exec -it backend hp vault set pve-token

# 3. Create API token
docker compose exec backend hp token create

# 4. Restart to load vault secrets into config
docker compose restart backend

Vault Keys

Vault Key	Purpose	Value Format
secret-key	API token signing key	{"value": "random_hex_64"}
admin-secret	Admin authentication	{"secret": "random_hex_32"}
webhook-secret	Event webhook verification	{"value": "random_hex_32"}
jumpserver-token	SSH relay auth	{"value": "random_hex_48"}
pve-token	Proxmox VE API access	{"token": "user@realm!tokenid=uuid"}

http-sequence Vault Entries

For adopted services (e.g., Authentik), vault entries include connection details:

{
  "base_url": "https://auth.example.lan",
  "headers": { "Authorization": "Bearer <token>" },
  "verify_tls": true
}

Data Directory

~/.hp/
├── homepilot.db              SQLite database
├── .env                      Local environment config
├── .secret_key               Auto-generated signing key (0o600)
├── .vault_passphrase         Auto-generated passphrase (0o600)
├── artifacts/
│   ├── .git/                 Local git repo for artifact history
│   ├── YYYY/MM/              Organized by date
│   └── README.md             Auto-generated layout guide
└── vault/
    ├── master.protected       Age-encrypted master identity
    └── secrets/
        ├── pve-token.age
        └── <service>.age

Security Considerations

• Passphrase file ({data_dir}/.vault_passphrase) is mode 0o600 — only the HomePilot process can read it
• Vault data is encrypted with age (X25519 + ChaCha20-Poly1305)
• Auto-generated secrets are ephemeral if the passphrase file cannot be persisted (read-only filesystem)
• In production (HP_ENV=production), HP_SECRET_KEY must be explicitly set or stored in vault — auto-generation is forbidden

Export and Backup

# Export data directory as tarball
hp export > homepilot-backup.tar.gz

# Restore from tarball
hp import homepilot-backup.tar.gz

# Rebuild KB search index after restore
hp kb reindex

See Also

• Installation — Full deployment walkthrough
• Security — Auth model, RBAC, and token lifecycle
• Artifacts — Artifact spec and data directory layout