Configuration

Environment Variables

All configuration is via environment variables or database-backed settings. Copy .env.example to .env and adjust.

Core Settings

Tailscale

Configure via Settings → Tailscale in the dashboard or via environment variables. Discovery tags filter which devices appear in PodWarden.

Authentication

PodWarden supports three auth modes, configurable in order of priority:

OIDC (Recommended)

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

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.

Roles:

• admin — Full access to all resources, settings, user management, secrets, token creation
• operator — Manage hosts, clusters, workloads, deployments, storage
• viewer — Read-only access to all resources

Registry

Set fleet-wide defaults for container image registry and tag. Individual stacks can override these.

SSH / Provisioning

PodWarden uses SSH to provision hosts via Ansible — installing Docker, k3s-agent, and GPU drivers. Generate SSH key pairs from Settings → Secrets → Generate SSH Key Pair or provide your own.

PodWarden Hub

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:

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:

Click Test OIDC to verify the discovery endpoint responds correctly.

Hub Settings

Configure the PodWarden Hub connection under Settings → Hub:

Click Test Connection to verify the API key is valid and Hub is reachable. See Connecting to Hub for the full setup guide.

Tailscale Settings

Configure host discovery under Settings → Tailscale:

The API key and tailnet are stored as encrypted app secrets.

Registry Settings

Configure fleet-wide defaults under Settings → Registry:

MCP Tokens

Machine-readable API tokens for automation and integrations. Create and manage tokens under Settings → MCP Tokens.

Creating a Token

1. Go to Settings → MCP Tokens
2. Click Create Token
3. Set a Name (descriptive label, e.g. "CI/CD Pipeline")
4. Choose a Role — determines API access level:
   • admin — Full access to all resources
   • operator — Manage hosts, clusters, workloads, deployments, storage
   • viewer — Read-only access
5. Set Expiry — 1 to 365 days, or no expiry
6. 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/hosts

Token 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

1. Go to Settings → Secrets
2. Click Create Secret
3. Enter a Key (unique identifier) and Value
4. 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:

1. Go to Settings → Secrets
2. Click Generate SSH Key Pair
3. Enter a name for the key pair
4. 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.