pve-agentsReference
Environment variables
Configuration read when the controller starts.
.env.example is authoritative. Copy
it to .env for development; use a root-readable EnvironmentFile in production.
Controller and sign-in
| Variable | Purpose |
|---|---|
DATABASE_PATH | Persistent SQLite path; parent directory must be writable. |
CONTROLLER_ID | Stable deployment UUID used in ownership markers. |
CONTROLLER_HOST, CONTROLLER_PORT | Listener address and port; default is 127.0.0.1:3000. |
CONTROLLER_URL | Exact browser origin; required for correct cookies and CSRF handling. |
CONTROLLER_AUTH_SECRET | 32+ character signing secret for sessions and API keys. |
GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET | GitHub OAuth app used for operator sign-in. |
CONTROLLER_OPERATOR_GITHUB_ID | Numeric GitHub ID of the only permitted operator. |
Generate the signing secret with:
head -c 48 /dev/urandom | base64 | tr -d '
='Provisioning
| Variable | Purpose |
|---|---|
PROVISIONING_ENABLED | Gates Proxmox writes; default false. |
PROXMOX_URL, PROXMOX_TOKEN_ID, PROXMOX_TOKEN_SECRET | Proxmox API connection. |
PROXMOX_NODE, PROXMOX_TEMPLATE_VMID, PROXMOX_POOL, PROXMOX_BRIDGE | Workspace placement and network. |
PROXMOX_VMID_MIN | Lower bound for disposable workspace VMIDs. |
WORKSPACE_SSH_USER, WORKSPACE_SSH_KEY_PATH | SSH identity used to manage workspaces. |
WORKSPACE_SUBNET | Accepted workspace network for address discovery. |
Enabling provisioning requires the authentication and GitHub settings in addition to a valid Proxmox configuration.
Repository access and worker
| Variable | Purpose |
|---|---|
GITHUB_APP_ID, GITHUB_APP_INSTALLATION_ID, GITHUB_APP_PRIVATE_KEY_PATH | GitHub App used for clone and push. |
GITHUB_TOKEN_REFRESH_SECONDS | Refreshes the short-lived workspace GitHub token; default 2400. |
WORKER_ENABLED | Runs the operation worker in the controller; default false. |
WORKER_INTERVAL_SECONDS | Worker interval in seconds; default 5. |
WORKSPACE_ACTIVITY_INTERVAL_SECONDS | Ready-workspace activity interval; default 30. |
Managed in Settings
Agent credentials and reaping policy are stored in the database and configured from Settings. Changes
to them do not need a controller restart. NODE_EXTRA_CA_CERTS, if required, must be set by systemd
or the process environment because Node reads it before the application loads the env file.
Last updated on