Configuration
Configure authentication, Hub, MCP tokens, and system settings
Environment Variables
All configuration is via environment variables or database-backed settings. Copy .env.example to .env and adjust.
Coming in a future release: PodWarden is moving to a config v2 model where the backend reads only a small bootstrap set of environment variables directly from the environment (DATABASE_URL, PW_ENCRYPTION_KEY, PW_FIRST_ADMIN_USER/PW_FIRST_ADMIN_PASSWORD, PW_LISTEN_PORT, PW_LOG_LEVEL). Everything else described on this page becomes a database-backed setting managed from the UI or API instead of a .env value. An operator will still be able to pin an individual setting to an environment variable when needed — while a setting is pinned this way, it can't be changed from Settings. This is not available in the current release, and there is no environment variable yet to opt into it. The tables below describe configuration as it works today.
Core Settings
| Variable | Default | Description |
|---|---|---|
PW_POSTGRES_PASSWORD | podwarden | Database password — change this before exposing the database port |
PW_POSTGRES_USER | podwarden | Database user |
PW_POSTGRES_DB | podwarden | Database name |
PW_DB_PORT | 5434 | Host-mapped PostgreSQL port. The API always connects to the database over 127.0.0.1 — there is no separate database-host variable |
PW_API_PORT | 8000 | API port |
PW_UI_PORT | 3000 | UI port |
Host Networking
PodWarden does not require any special configuration for mesh VPNs. When a host is probed, every detected network interface (LAN, mesh, public) is recorded in host_interfaces and made available as a connection path. See the Networking guide for the interface-kind model and how PodWarden picks the path for provisioning, K3s joins, and storage reachability checks.
Authentication
PodWarden supports three auth modes, configurable in order of priority:
OIDC (Recommended)
| Variable | Description |
|---|---|
OIDC_ISSUER | OIDC provider URL (e.g. Keycloak realm). Alias: OIDC_ISSUER_URL |
OIDC_CLIENT_ID | OAuth client ID |
OIDC_CLIENT_SECRET | OAuth client secret |
FRONTEND_URL | Base URL of the UI — also used to build the OIDC callback and SSH-approval links |
None of these are PW_-prefixed. There is no separate redirect-URI variable — the callback is derived from FRONTEND_URL.
The frontend initiates the PKCE flow with your configured provider. After login, the provider returns an authorization code that is exchanged for access and refresh tokens. The access token is sent as a Bearer token on API requests.
Any OpenID Connect provider works: Keycloak, Google, GitHub, Authentik, etc.
Temporary Admin
| Variable | Description |
|---|---|
PW_TEMP_ADMIN_USER | Temporary admin username |
PW_TEMP_ADMIN_PASSWORD | Temporary admin password |
Useful for initial setup. Creates a temporary admin account that bypasses OIDC. Remove these variables after creating permanent OIDC or local user accounts.
Local Users
Managed via Settings → Users. Create accounts with email, password, and role. No external identity provider required.
Each account has a stored role field (admin or readonly), but it is not enforced — every authenticated user has the same access, secret values included. Earlier releases had a real operator/viewer/admin permission matrix, then a binary model that actually restricted access; neither is enforced today.
Registry
| Variable | Default | Description |
|---|---|---|
PW_DEFAULT_REGISTRY | — | Default container registry URL, used when Settings has none set |
The default image tag is a Settings-only field (default latest) — there is no environment variable for it. Set the fleet-wide registry default via PW_DEFAULT_REGISTRY or Settings → Registry; individual stacks can override either.
SSH / Provisioning
| Variable | Description |
|---|---|
PW_SSH_KEY_PATH | Path to SSH private key for host provisioning and cluster discovery |
K3S_SSH_USER | SSH user used when fetching a join token from an existing cluster's control-plane host (default: root) |
PodWarden uses SSH to provision hosts via Ansible — installing Docker, k3s-agent, and GPU drivers. The SSH user for provisioning a host is a per-host field (ssh_user, default root) set when you add or edit the host — not a global environment variable. Generate SSH key pairs from Settings → Secrets → Generate SSH Key Pair or provide your own.
PodWarden Hub
| Variable | Description |
|---|---|
PODWARDEN_HUB_URL | Your organization's Hub URL — no default, must be set before Hub features work |
PODWARDEN_HUB_API_KEY | Hub instance key (starts with pwh_) |
Connect your PodWarden instance to PodWarden Hub for catalog access. See Connecting to Hub.
Database-Backed Settings
Some settings are stored in the database and configurable via the Settings page. These override environment variables when set.
SMTP
Configure email notifications under Settings → System Config → SMTP:
| Field | Description |
|---|---|
| Host | SMTP server hostname |
| Port | SMTP server port (587 for TLS) |
| Username | SMTP auth username |
| Password | SMTP auth password |
| From Address | Sender email address |
| TLS | Enable STARTTLS |
Click Test Email to send a test message and verify your configuration.
OIDC
Override OIDC environment variables from the UI under Settings → System Config → OIDC:
| Field | Description |
|---|---|
| Issuer URL | OIDC provider URL |
| Client ID | OAuth client ID |
| Client Secret | OAuth client secret |
| Redirect URI | Callback URL |
Click Test OIDC to verify the discovery endpoint responds correctly.
Hub Settings
Configure the PodWarden Hub connection under Settings → Hub:
| Field | Description |
|---|---|
| Hub URL | The URL of your PodWarden Hub instance — no default is pre-filled |
| API Key | Your organization's Hub instance key (pwh_...) |
Click Test Connection to verify the API key is valid and Hub is reachable. See Connecting to Hub for the full setup guide.
Registry Settings
Configure fleet-wide defaults under Settings → Registry:
| Field | Description |
|---|---|
| Default Registry URL | Default container registry for all workloads |
| Default Image Tag | Default tag (e.g. latest, stable) |
MCP Tokens
Machine-readable API tokens for automation and integrations. Create and manage tokens under Settings → MCP Tokens.
Creating a Token
- Go to Settings → MCP Tokens
- Click Create Token
- Set a Name (descriptive label, e.g. "CI/CD Pipeline")
- Set a Role (
adminorreadonly) — stored and shown in the UI, but not currently enforced: a token of either role has the same access - Set Expiry — 1 to 365 days, or no expiry
- Copy the token immediately — it starts with
pwm_and is shown only once
Using a Token
Include the token as a Bearer token in API requests:
curl -H "Authorization: Bearer pwm_a1b2c3d4e5f6..." \
https://podwarden.example.com/api/v1/hostsToken Management
- Revoke — Immediately invalidate a token
- Reissue — Generate a new key while keeping the same name and role
- Audit Log — Every API request made with the token is logged with method, path, and status code
View audit logs per token or across all tokens under Settings → MCP Tokens → Audit.
Use Cases
- CI/CD pipelines — Record deployments via
POST /api/v1/deployments - Monitoring — Read cluster status and workload health
- Automation scripts — Create/manage workloads programmatically
- MCP (Model Context Protocol) — Allow AI agents to interact with your fleet
Secrets
PodWarden provides encrypted secret storage. Manage secrets under Settings → Secrets.
Creating Secrets
- Go to Settings → Secrets
- Click Create Secret
- Enter a Key (unique identifier) and Value
- Save — the value is encrypted at rest
Secrets can be referenced by stacks via secret_refs and are injected as environment variables at deploy time.
SSH Key Pairs
PodWarden can generate ed25519 SSH key pairs for host provisioning:
- Go to Settings → Secrets
- Click Generate SSH Key Pair
- Enter a name for the key pair
- PodWarden generates the keys and stores both the private and public key as secrets
View which key pairs are in use by provisioned hosts under SSH Key Pairs in Use.