Environment Variables

This page lists the environment variables and config files the homelab actually reads, grouped by the tool that consumes them. Every entry maps to a committed *.example file. Copy it, drop the .example suffix, and fill in the values.

Secrets live in Bitwarden, not in files

The only long-lived secret kept locally is BWS_ACCESS_TOKEN. Everything the cluster needs at runtime lives in Bitwarden Secrets Manager and is synced in by the External Secrets Operator. The variables below are what bootstrap and provision the lab, not what run it.

Runner .env (project root)

The containerised runner and the Taskfile both load a .env file in the repo root. Taskfile.yaml reads it via dotenv: [".env"], and compose.yaml passes these four variables into the runner container.

Source: env.example. Run cp env.example .env.

Variable	Purpose
BWS_ACCESS_TOKEN	Bitwarden Secrets Manager access token. Bootstraps the External Secrets Operator and is used by the Kubernetes Ansible playbook.
CLOUDFLARE_API_TOKEN	Cloudflare API token. Creates the R2 state bucket and is used by Terragrunt’s Cloudflare provider.
AWS_ACCESS_KEY_ID	Access key ID for the Cloudflare R2 (S3-compatible) bucket that holds Terragrunt remote state.
AWS_SECRET_ACCESS_KEY	Secret access key for the same R2 bucket.

Terragrunt account.hcl

Per-environment settings (prod, non-prod) for VM provisioning and remote state. These are configured by editing the file. Each value also falls back to an environment variable through get_env(...), so it can be overridden without touching the file.

Source: terragrunt/infrastructure-live/prod/account.hcl.example

Variable	Purpose
PVE_ENDPOINT	Proxmox VE API endpoint, for example https://<node>:8006/.
PVE_API_TOKEN	Proxmox API token used to provision the Talos and TrueNAS VMs.
PVE_USERNAME, PVE_PASSWORD	Proxmox credentials, as an alternative to the API token.
PVE_AUTH_TICKET, PVE_CSRF_TOKEN	Optional Proxmox ticket-based auth.
CLOUDFLARE_ACCOUNT_ID	Cloudflare account ID. Also forms the R2 endpoint URL.
CLOUDFLARE_JURISDICTION	Optional R2 jurisdiction suffix, for example EU.
R2_BUCKET_NAME	Name of the R2 remote-state bucket (default homelab-as-code).
TS_AUTHKEY	Tailscale auth key injected into the Talos nodes.

Ansible

pve-cluster (Layer 2)

Source	What to set
TS_KEY env var	Tailscale auth key for the Proxmox nodes. Export it before running the playbook; the tailscale-bootstrap role reads it.
inventory.yml.example	Per-node ansible_host IPs and the ansible_user.

Note

Tailscale uses two separate keys: TS_KEY for the Proxmox hosts (Ansible, Layer 2) and TS_AUTHKEY for the Talos nodes (Terragrunt, Layer 4).

ansible-k8s

Source	What to set
host_vars/localhost.yml.example	organization_id and project_id for the Bitwarden ClusterSecretStore.

R2 bucket bootstrap (one-time)

A standalone OpenTofu module that creates the R2 bucket before Terragrunt has a state backend. It is run once, then Terragrunt uses the bucket for everything else.

Sources: tofu/bootstrap-r2-bucket/env.example and terraform.tfvars.example.

Variable	Purpose
CLOUDFLARE_API_TOKEN	Cloudflare token with R2 permissions.
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY	R2 S3 credentials.
CLOUDFLARE_ACCOUNT_ID	Account ID used to build the R2 endpoint.
R2_BUCKET_NAME	Bucket name (optional, has a default).
R2_LOCATION	Bucket location hint (optional).
account_id (tfvar)	Cloudflare account ID, set in terraform.tfvars.

For the accounts and tokens behind these variables, see Prerequisites.