Skip to content
LabTether

Environment Variables

Complete reference for all environment variables recognized by LabTether. Set these in your .env file or deployment environment.

Variables marked runtime can also be changed at runtime via the hub admin UI (Settings). All others are read only at startup.

Required Variables

These must be set for the hub to start. In the split-Postgres deploy stack, secrets are auto-generated on first boot and persisted to disk.

Variable Description
POSTGRES_PASSWORD PostgreSQL password. Auto-generated in split-Postgres deploy.
LABTETHER_ADMIN_PASSWORD Admin login password. Leave blank to complete setup in the browser at /setup.
LABTETHER_OWNER_TOKEN Owner bearer token. Auto-generated as 64-char hex if omitted.
LABTETHER_API_TOKEN Internal API/service token. Defaults to owner token if omitted.
LABTETHER_ENCRYPTION_KEY Credential encryption key (base64 of 32 random bytes). Auto-generated if omitted. Generate with: openssl rand -base64 32

Authentication & Identity

Bootstrap Credentials

Variable Default Description
LABTETHER_ADMIN_USERNAME admin Bootstrap admin username.
LABTETHER_ADMIN_PASSWORD -- Bootstrap admin password. When blank, first-run setup is completed in the browser.
LABTETHER_SETUP_TOKEN -- Dedicated one-time token for creating the first owner when no admin password is configured. Prefer the file form in containers.
LABTETHER_SETUP_TOKEN_FILE -- Path to the first-run setup token. The split deploy stack generates this automatically at /bootstrap/auth/setup-token.
LABTETHER_OWNER_TOKEN auto-generated Owner bearer token. Persisted in install state on first boot.
LABTETHER_API_TOKEN owner token Internal API/service token. Persisted in install state on first boot.
LABTETHER_API_TOKEN_FILE -- File path where the runtime API token is written. Used by the deploy stack for inter-service auth.
LABTETHER_TRUST_PROXY_HOPS 0 Number of trusted reverse-proxy hops allowed to supply client IP forwarding headers to the console login limiter. Leave 0 unless every configured proxy overwrites X-Forwarded-For.
LABTETHER_ENCRYPTION_KEY auto-generated Master AES-256 key for credential storage (base64-encoded 32 bytes).
LABTETHER_TOTP_KEY derived from encryption key Explicit AES-256 key for TOTP secret encryption (base64-encoded 32 bytes). Derived from LABTETHER_ENCRYPTION_KEY via HKDF-SHA256 if omitted.

OIDC / Single Sign-On

Variable Default Description
LABTETHER_OIDC_ENABLED auto Enables OIDC login. Auto-enables when issuer URL or client ID is set.
LABTETHER_OIDC_ISSUER_URL -- OIDC issuer discovery URL (e.g., https://auth.example.com).
LABTETHER_OIDC_CLIENT_ID -- OIDC client ID.
LABTETHER_OIDC_CLIENT_SECRET -- OIDC client secret.
LABTETHER_OIDC_DISPLAY_NAME Single Sign-On Login button label for the OIDC provider.
LABTETHER_OIDC_SCOPES openid,profile,email Comma-separated OIDC scopes to request.
LABTETHER_OIDC_ROLE_CLAIM labtether_role JWT claim name for role mapping (fallback: groups).
LABTETHER_OIDC_DEFAULT_ROLE viewer Role assigned when no claim mapping matches.
LABTETHER_OIDC_ADMIN_ROLES admin Comma-separated claim values that grant admin privileges.
LABTETHER_OIDC_OPERATOR_ROLES operator Comma-separated claim values that grant operator privileges.
LABTETHER_OIDC_AUTO_PROVISION true Auto-create hub users on first successful OIDC login.

SSH Hub Identity

Variable Default Description
LABTETHER_SSH_KEY_TYPE ed25519 SSH keypair type for hub identity. Set to rsa for RSA-4096; anything else uses Ed25519.

Database

Variable Default Description
POSTGRES_DB labtether PostgreSQL database name.
POSTGRES_USER labtether PostgreSQL username.
POSTGRES_PASSWORD auto-generated in deploy stack PostgreSQL password.
DATABASE_URL derived from above Full connection string (e.g., postgres://user:pass@host:5432/db?sslmode=disable). Constructed automatically in the deploy stack entrypoint.
LABTETHER_DB_STATEMENT_TIMEOUT 30s PostgreSQL statement timeout for all queries.
LABTETHER_DB_MAX_CONNS 10 Maximum database connections in pool.
LABTETHER_DB_MIN_CONNS 2 Minimum database connections to maintain.
LABTETHER_DB_MAX_CONN_LIFETIME_MIN 5 Maximum connection lifetime in minutes.
LABTETHER_DB_MAX_CONN_IDLE_TIME_MIN 1 Maximum connection idle time in minutes.

TLS & Certificates

Variable Default Description
LABTETHER_TLS_MODE auto TLS mode: auto (built-in CA), external (user certs), disabled.
LABTETHER_TLS_CERT -- Path to server certificate file, PEM format (external mode only).
LABTETHER_TLS_KEY -- Path to server private key file, PEM format (external mode only).
LABTETHER_DATA_DIR /data (Docker), data (local) Base directory for auto-generated certs and persistent install state.
LABTETHER_CA_SHARE_DIR /ca Directory where the hub copies its public CA cert for agent/console containers.
LABTETHER_TLS_CA_FILE -- Agent: path to CA cert for hub verification.
LABTETHER_TLS_SKIP_VERIFY false Agent: skip cert verification (dev only, logs a warning).
NODE_EXTRA_CA_CERTS -- Web console: path to CA cert for Node.js HTTPS calls to the hub backend.

Network & Ports

Variable Default Description
API_PORT 8080 HTTP listener port (health checks, redirects). Alias: LABTETHER_HTTP_PORT.
LABTETHER_HTTPS_PORT 8443 HTTPS listener port.
LABTETHER_HTTP_BIND 127.0.0.1 Host bind address for HTTP port 8080.
LABTETHER_HTTPS_BIND 0.0.0.0 Host bind address for HTTPS port 8443.
LABTETHER_CONSOLE_BIND 127.0.0.1 Host bind address for web console port 3000.
LABTETHER_CONSOLE_URL derived from request Override for the advertised console URL on the hub landing page.
LABTETHER_EXTERNAL_URL -- External hub URL (no trailing slash) for references in generated links.
NEXT_PUBLIC_HUB_API_PORT 8443 (TLS) / 8080 (deploy stack) Browser-side backend port for WebSocket and API calls.
LABTETHER_SHUTDOWN_TIMEOUT_SECONDS 15 Graceful shutdown timeout in seconds (minimum 1).

Connectors

Proxmox VE

Variable Default Description
PROXMOX_BASE_URL -- Proxmox VE base URL (e.g., https://proxmox.local:8006). Required to enable the connector.
PROXMOX_TOKEN_ID -- API token ID (format: user@realm!tokenname).
PROXMOX_TOKEN_SECRET -- API token secret.
PROXMOX_DEFAULT_NODE -- Default cluster node for operations.
PROXMOX_HTTP_TIMEOUT 10s HTTP request timeout.
PROXMOX_SKIP_VERIFY false Skip TLS certificate verification.
PROXMOX_CA_CERT_PEM -- Custom CA certificate in PEM format.

Proxmox Backup Server

Variable Default Description
PBS_BASE_URL -- PBS base URL. Required to enable the connector.
PBS_TOKEN_ID -- API token ID.
PBS_TOKEN_SECRET -- API token secret.
PBS_HTTP_TIMEOUT 10s HTTP request timeout.
PBS_SKIP_VERIFY false Skip TLS certificate verification.
PBS_CA_CERT_PEM -- Custom CA certificate in PEM format.

Portainer

Variable Default Description
PORTAINER_BASE_URL -- Portainer base URL. Without a URL and authentication, the connector remains unavailable and health, reads, and actions fail closed.
PORTAINER_API_KEY -- API key for authentication.
PORTAINER_USERNAME -- Username (alternative to API key).
PORTAINER_PASSWORD -- Password (alternative to API key).
PORTAINER_HTTP_TIMEOUT 10s HTTP request timeout.
PORTAINER_SKIP_VERIFY false Skip TLS certificate verification.

Home Assistant

Variable Default Description
HA_BASE_URL -- Home Assistant base URL (e.g., https://homeassistant.local:8123).
HA_TOKEN -- Long-lived access token.
HA_HTTP_TIMEOUT 10s HTTP request timeout.
HA_SKIP_VERIFY false Skip TLS certificate verification.

Remote Access

SSH Terminal

Fallback credentials used when no per-asset SSH config exists. Per-asset config in the UI takes precedence.

Variable Default Description
SSH_USERNAME -- Default SSH username.
SSH_PASSWORD -- Default SSH password.
SSH_PORT 22 Default SSH port.
SSH_HOST_KEY -- Expected host key for verification.
SSH_PRIVATE_KEY -- Private key in PEM format (raw text).
SSH_PRIVATE_KEY_B64 -- Private key, base64-encoded (alternative to SSH_PRIVATE_KEY).
SSH_PRIVATE_KEY_PATH -- File path to private key (alternative to inline).
SSH_PRIVATE_KEY_PASSPHRASE -- Passphrase for encrypted private keys.

Key lookup order: SSH_PRIVATE_KEY_B64 > SSH_PRIVATE_KEY > SSH_PRIVATE_KEY_PATH.

Remote Desktop (guacd)

Variable Default Description
GUACD_HOST guacd (Docker) Hostname of the Apache Guacamole proxy daemon.
GUACD_PORT 4822 TCP port for the guacd server.
LABTETHER_DESKTOP_DEBUG false Enable desktop protocol debug logging.

Security Hardening

Command Execution

Controls which binaries can be executed via the structured command API.

Variable Default Description
LABTETHER_EXEC_ALLOWLIST_MODE true Enable binary execution allowlist enforcement.
LABTETHER_EXEC_ALLOWED_BINARIES built-in list (90+) Comma-separated allowed binary names. Empty uses the built-in allowlist.
LABTETHER_EXEC_BLOCKED_BINARIES -- Comma-separated blocked binary names. Applied on top of the allowlist.

Shell Commands

Controls which shell commands can be executed via the interactive command API.

Variable Default Description
LABTETHER_SHELL_COMMAND_ALLOWLIST_MODE true Enable shell command prefix allowlist. Docker Compose default: false.
LABTETHER_SHELL_COMMAND_ALLOWLIST_PREFIXES built-in list (16) Comma-separated allowed command prefixes. Empty uses the built-in list (e.g., uptime, df, ps, docker ps).
LABTETHER_SHELL_COMMAND_BLOCKED_SUBSTRINGS built-in list (6) Comma-separated blocked patterns. Empty uses the built-in list (e.g., rm -rf /, fork bombs, mkfs).

Outbound Network

Controls outbound HTTP/WebSocket connections made by the hub or agent.

Variable Default Description
LABTETHER_OUTBOUND_ALLOWLIST_MODE false Require every outbound destination to match LABTETHER_OUTBOUND_ALLOWED_HOSTS.
LABTETHER_OUTBOUND_ALLOW_PRIVATE auto (true in deploy artifacts) Allow connections to private/RFC1918/ULA targets. Deploy artifacts enable this because LAN management is core LabTether functionality. runtime
LABTETHER_OUTBOUND_ALLOW_LOOPBACK false Allow connections to services inside the hub container. Deploy artifacts keep this disabled to prevent container-local pivots.
LABTETHER_OUTBOUND_ALLOW_LINK_LOCAL false Allow link-local and cloud metadata ranges. Keep disabled; enabling private LAN access does not enable link-local targets.
LABTETHER_OUTBOUND_ALLOWED_HOSTS -- Comma-separated allowed hostnames (when allowlist mode is on).
LABTETHER_OUTBOUND_ALLOWED_SCHEMES https,wss Comma-separated allowed URL schemes. Docker Compose default: http,https,ws,wss.

Log Sanitization

Variable Default Description
LABTETHER_LOG_SANITIZE_MAX_LEN 512 Maximum length for sanitized log field values (range: 64-4096).

Worker & Job Queue

Variable Default Description
JOB_WORKERS 4 Number of concurrent job worker goroutines (minimum 1).
JOB_POLL_INTERVAL 500ms Polling interval for job queue checks.
QUEUE_MAX_DELIVERIES 5 Maximum delivery attempts before dead-lettering a job. runtime
RETENTION_APPLY_INTERVAL 5m How often the data retention pruner runs. runtime

Console & UI Defaults

These set initial values for dashboard display. All are runtime settings — they can be changed in the admin UI after startup.

Variable Default Description
LABTETHER_POLL_INTERVAL_SECONDS 5 Dashboard status refresh interval (range: 2-120 seconds).
LABTETHER_DEFAULT_TELEMETRY_WINDOW 1h Default telemetry chart range (15m, 1h, 6h, 24h).
LABTETHER_DEFAULT_LOG_WINDOW 1h Default log query range (15m, 1h, 6h, 24h).
LABTETHER_LOG_QUERY_LIMIT 120 Maximum events per log query (range: 20-500).
LABTETHER_DEFAULT_ACTOR_ID owner Default actor identity for commands and actions.
LABTETHER_DEFAULT_ACTION_DRY_RUN true Default dry-run mode for connector actions.
LABTETHER_DEFAULT_UPDATE_DRY_RUN true Default dry-run mode for update plan execution.

Policy Flags

All are runtime settings.

Variable Default Description
STRUCTURED_ENABLED true Enable structured terminal command mode.
INTERACTIVE_ENABLED true Enable interactive terminal and desktop sessions.
CONNECTOR_ENABLED true Enable connector action execution.

Service Discovery

Default agent service discovery settings. All are runtime settings.

Variable Default Description
LABTETHER_SERVICES_DISCOVERY_DEFAULT_DOCKER_ENABLED true Enable Docker-backed service discovery.
LABTETHER_SERVICES_DISCOVERY_DEFAULT_PROXY_ENABLED true Enable reverse proxy API discovery.
LABTETHER_SERVICES_DISCOVERY_DEFAULT_PROXY_TRAEFIK_ENABLED true Enable Traefik route discovery.
LABTETHER_SERVICES_DISCOVERY_DEFAULT_PROXY_CADDY_ENABLED true Enable Caddy admin API route discovery.
LABTETHER_SERVICES_DISCOVERY_DEFAULT_PROXY_NPM_ENABLED true Enable Nginx Proxy Manager API discovery.
LABTETHER_SERVICES_DISCOVERY_DEFAULT_PORT_SCAN_ENABLED true Enable local host port scanning.
LABTETHER_SERVICES_DISCOVERY_DEFAULT_PORT_SCAN_INCLUDE_LISTENING true Include listening sockets in port scans.
LABTETHER_SERVICES_DISCOVERY_DEFAULT_PORT_SCAN_PORTS -- Optional port list for local scans.
LABTETHER_SERVICES_DISCOVERY_DEFAULT_LAN_SCAN_ENABLED false Enable LAN CIDR service scanning.
LABTETHER_SERVICES_DISCOVERY_DEFAULT_LAN_SCAN_CIDRS -- CIDR list for LAN scanning.
LABTETHER_SERVICES_DISCOVERY_DEFAULT_LAN_SCAN_PORTS -- Port list for LAN scanning.
LABTETHER_SERVICES_DISCOVERY_DEFAULT_LAN_SCAN_MAX_HOSTS 64 Max hosts probed per scan cycle (range: 1-1024).

Prometheus & Metrics

All are runtime settings.

Variable Default Description
LABTETHER_PROMETHEUS_SCRAPE_ENABLED false Expose /metrics endpoint for Prometheus scraping.
LABTETHER_PROMETHEUS_REMOTE_WRITE_ENABLED false Push metrics to a Prometheus-compatible remote_write endpoint.
LABTETHER_PROMETHEUS_REMOTE_WRITE_URL -- Target URL for remote_write (e.g., https://prometheus.example.com/api/v1/write).
LABTETHER_PROMETHEUS_REMOTE_WRITE_USERNAME -- HTTP Basic Auth username for remote_write.
LABTETHER_PROMETHEUS_REMOTE_WRITE_PASSWORD -- HTTP Basic Auth password for remote_write (stored encrypted).
LABTETHER_PROMETHEUS_REMOTE_WRITE_INTERVAL 30s Push interval for remote_write.
LABTETHER_PROCESS_METRICS_ENABLED false Collect per-process CPU and memory metrics.
LABTETHER_PROCESS_METRICS_TOP_N 20 Max processes tracked per asset (range: 1-200).

Remote Access Preferences

Variable Default Description
LABTETHER_REMOTE_ACCESS_MODE serve Preferred remote access mode: serve (Tailscale HTTPS), manual, off. runtime
LABTETHER_TAILSCALE_SERVE_TARGET -- Upstream URL for tailscale serve. When blank, suggests the local console. runtime
LABTETHER_TAILSCALE_MANAGED false Opt-in for host-control integration with managed Tailscale actions.

Agent Distribution

Variable Default Description
LABTETHER_AGENT_DIR /opt/labtether/agents Directory for baked-in agent binaries (Docker image build time).
LABTETHER_AGENT_CACHE_DIR /data/agents Directory for runtime agent binary cache.
LABTETHER_AGENT_MANIFEST_REFRESH false Enable runtime manifest refresh from GitHub Releases.
LABTETHER_AGENT_TOKEN_TTL_HOURS 720 (30 days) Agent token time-to-live in hours.

Agent Configuration

These are read by the agent binary, not the hub. Included here because they appear in docker-compose.yml.

Variable Default Description
AGENT_PORT 8090 Agent HTTP listener port.
AGENT_ASSET_ID -- Asset identifier for this agent instance.
AGENT_SOURCE -- Source identifier (e.g., labtether-agent).
AGENT_GROUP_ID -- Optional default group assignment for heartbeat identity.
LABTETHER_API_BASE_URL -- Hub API URL the agent connects to (e.g., https://labtether:8443).
LABTETHER_WS_URL -- Hub WebSocket URL (e.g., wss://labtether:8443/ws/agent).
LABTETHER_API_TOKEN -- API token for hub authentication.
LABTETHER_TLS_CA_FILE -- Path to CA cert for hub certificate verification.
LABTETHER_TLS_SKIP_VERIFY false Skip hub certificate verification (dev only).

Install & Image Overrides

Used by the deploy stack and release tooling.

Variable Default Description
LABTETHER_VERSION in .env.deploy.example Release version pin for repo-checkout deploys.
LABTETHER_IMAGE derived from version All-in-one Docker image override.
POSTGRES_IMAGE postgres:18-alpine PostgreSQL image override (compose split mode).
GUACD_IMAGE pinned guacamole/guacd:1.6.0 Guacd image override (multi-arch digest pinned).
LABTETHER_MANAGED_POSTGRES false Signal that the deploy stack manages Postgres credentials automatically.
LABTETHER_ENV production Environment identifier.

Operational & Debug

Variable Default Description
APP_VERSION dev Application version string (shown in /version endpoint).
DEV_MODE false Enable developer mode (exposes pprof endpoints at /debug/pprof/*).
LABTETHER_DISABLE_MDNS false Disable mDNS/Bonjour discovery advertising.
LABTETHER_ENABLE_LOCAL_TERMINAL false Enable owner-only hub-local PTY terminal (target: __hub__).
LABTETHER_LOCAL_TERMINAL_SHELL auto-detect Shell override for hub-local PTY sessions. Auto-detects /bin/bash, /bin/ash, /bin/sh.

Demo Mode

Variable Default Description
LABTETHER_DEMO_MODE false Enable demo mode (public, read-only, auto-authenticated).
LABTETHER_DEMO_CONFIRM -- Required confirmation string: yes-this-is-a-demo-instance. Prevents accidental activation.

Notes

  • Duration format: All duration variables accept Go duration syntax (e.g., 10s, 5m, 1h, 500ms).
  • Runtime settings are seeded from environment variables at startup but can be changed live in Settings. The env var value is only used as the initial default.
  • Installation state: Security tokens (owner, API, encryption key) are persisted to LABTETHER_DATA_DIR/install-state.json on first boot. Setting the env var on subsequent runs overrides the persisted value.
  • Connector TLS: All connectors support _SKIP_VERIFY and _CA_CERT_PEM for custom certificate handling.
  • Docker Compose defaults: Some security variables use different defaults in docker-compose.yml than the Go binary to accommodate inter-container communication. The Docker-specific values are noted in the descriptions above.