proxmox/docs/04-configuration/PROXMOX_API_SECRETS_DOTENV.md

Proxmox API Secrets and Dotenv

Purpose: How Proxmox API tokens and related secrets are stored for automation (dotenv).

---

Where secrets live

• Repo root: /.env — used by scripts run from the repo (validation, mcp-proxmox, maintenance). Do not commit (.env is in .gitignore).
• Template: /.env.example — placeholders only; copy to .env and fill, or run the token script below.

---

Proxmox API token (for API automations)

Scripts that call the Proxmox REST API (e.g. scripts/lib/proxmox-api.sh, scripts/validation/validate-config-files.sh, mcp-proxmox) expect:

Variable	Example	Description
PROXMOX_HOST	192.168.11.11	Proxmox host (primary; e.g. r630-01).
PROXMOX_PORT	8006	API port.
PROXMOX_USER	root@pam	User for the token.
PROXMOX_TOKEN_NAME	proxmox-workspace-api	Token ID (name).
PROXMOX_TOKEN_VALUE	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx	Token secret (UUID).

Authorization header: PVEAPIToken=${PROXMOX_USER}!${PROXMOX_TOKEN_NAME}=${PROXMOX_TOKEN_VALUE}

---

Obtain token and store in .env

Option A — Script (recommended): From repo root, with SSH to the Proxmox host:

./scripts/proxmox/create-and-store-proxmox-api-token.sh

This creates a new API token on the host, parses the secret from the one-time output, and updates /.env with PROXMOX_HOST, PROXMOX_USER, PROXMOX_TOKEN_NAME, PROXMOX_TOKEN_VALUE. Use --no-update-env to only print the values.

Option B — Manual: In Proxmox UI: Datacenter → Permissions → API Tokens → Add. Create token, copy the secret once, then set in .env:

PROXMOX_HOST=192.168.11.11
PROXMOX_PORT=8006
PROXMOX_USER=root@pam
PROXMOX_TOKEN_NAME=your-token-name
PROXMOX_TOKEN_VALUE=<paste-secret-here>

---

Other API secrets (dotenv)

Other automation secrets are also stored in the repo root .env (see /.env.example):

• NPMplus: NPM_EMAIL, NPM_PASSWORD, NPM_URL, etc.
• Cloudflare: CLOUDFLARE_API_TOKEN or CLOUDFLARE_EMAIL + CLOUDFLARE_API_KEY, zone IDs, tunnel tokens.
• Gitea: GITEA_TOKEN, GITEA_URL.
• Fastly: FASTLY_API_TOKEN.
• CoinGecko / CMC: COINGECKO_API_KEY, etc.

Keep .env out of version control and restrict access to the file (e.g. chmod 600 .env).

---

Refs: .env.example (root) | SCRIPT_ENV_VARS_REFERENCE | MASTER_SECRETS_INVENTORY