Skip to content
LabTether

Settings Reference

Runtime settings configurable from the web console and iOS companion app. Change one setting group at a time and validate behavior after each change.

Settings Domains

Domain Controls
Enrollment Agent bootstrap and token management
Connectors Collector behavior and integration credentials
Retention Windows for logs, metrics, audit events, and recordings
Runtime/System Behavior defaults and policy enforcement
Notifications Alert routing and escalation behavior

Auth and Access Control

Role Access Level
owner Full access; owner token + bootstrapped admin user (reserved/break-glass)
admin Full access except reserved owner-only semantics
operator Read/write operational workflows
viewer Read-only; blocked from mutating API methods (POST, PATCH, PUT, DELETE)

Admin-only areas: runtime settings, enrollment/agent token management, admin reset, user management endpoints. Optional OIDC sign-in is configured with LABTETHER_OIDC_* environment variables.

Web Console Settings Cards

User Access (Settings -> User Access)

Role Capabilities
admin/owner List users, create local users, update roles, reset passwords
operator/viewer Informational readout only

Backing endpoints: GET /api/auth/users, POST /api/auth/users, PATCH /api/auth/users/{id}

Tailscale HTTPS (Settings -> Tailscale HTTPS)

Field Description
Host detection Shows whether tailscale is installed, host is on a tailnet, and detected https://<host>.<tailnet>.ts.net URL
Serve status Shows whether tailscale serve is already active
Mode preference Tailscale HTTPS, Manual / Existing TLS, or Off For Now
Custom upstream Optional host-local tailscale serve upstream target
Verify action Refreshes host state after running the suggested command
Managed actions Enable HTTPS / Disable HTTPS (only when explicit host control is enabled)

Tip: The suggested tailscale serve command runs on the Docker host, not inside the LabTether container. Default target is http://127.0.0.1:3000.

Backing endpoint: GET /api/settings/tailscale/serve

TLS Management (Settings -> TLS Management)

Feature Description
Active TLS source built-in, deployment-managed external, uploaded override, or disabled
Certificate details Subject, issuer, expiry, and fingerprint
CA download Available when current source is LabTether-managed TLS
Upload override Admin: upload PEM certificate chain + matching PEM private key
Clear override Admin: restore startup TLS source
Restart backend Available when restart required for change to take effect

Uploaded private keys are encrypted before persistence. Uploaded overrides take precedence over startup env/config until cleared.

Backing endpoints: GET /api/settings/tls, POST /api/settings/tls, DELETE /api/settings/tls, POST /api/settings/restart

Advanced Security Setting

Key Env Var Values
security.outbound_allow_private LABTETHER_OUTBOUND_ALLOW_PRIVATE auto (default): secure private-network targets allowed for homelab connectors, loopback blocked. true: explicitly allow private outbound hosts. false: deny-private outbound posture.

Location: Settings -> Advanced Settings -> security. Insecure http:// and ws:// targets still require separate insecure-transport opt-in.

Policy Runtime Settings

Location: Settings -> Advanced Settings -> policy. Changes apply immediately to in-memory policy state.

Key Default Description
policy.structured_enabled true Structured terminal command mode
policy.interactive_enabled true Interactive terminal/desktop sessions
policy.connector_enabled true Connector action execution

iOS App Settings

Behavior

Key Location Default Description
lt.settings.mobileClientTelemetry Settings -> Behavior -> Share Mobile Telemetry disabled Opt in to authenticated mobile observability events (API latency, reconnect state, lifecycle diagnostics)
lt.settings.autoReconnect Settings -> Behavior -> Auto-reconnect enabled Auto-recover terminal/desktop after transient websocket drops
lt.settings.connectionDebugBanner Settings -> Behavior -> Connection Debug Banner disabled Overlay diagnostic line with websocket event metadata (trace id, close code, reconnect state)
lt.settings.queueOfflineActions Settings -> Behavior -> Queue Offline Actions enabled Queue runbook actions locally when hub is unreachable; replay when connectivity returns

Security

Key Location Default Description
lt.settings.requireBiometricRemoteAccess Settings -> Security -> Require Face ID for Remote Access enabled Require device-owner authentication before starting mobile terminal/desktop sessions
lt.settings.allowUntrustedTLS Settings -> Security -> Allow Untrusted TLS disabled Allow an untrusted/self-signed certificate for the exact selected HTTPS hub. Available on the login screen and in Settings; clears when the hub changes or is forgotten.

Notifications

Key Default Description
lt.settings.pushMinimumSeverity warning Foreground escalation threshold for push alerts
lt.settings.pushQuietHoursEnabled disabled Suppress non-critical banners/sounds during quiet hours
lt.settings.pushQuietHoursStartMinutes 22:00 Quiet hours start (when enabled)
lt.settings.pushQuietHoursEndMinutes 07:00 Quiet hours end (when enabled)
lt.settings.pushDigestWindowSeconds 180s Coalesce burst alert pushes into digest summaries

Live Activities

Key Default Description
lt.settings.liveActivitiesEnabled enabled Incident live activities on lock screen/dynamic island
lt.settings.liveActivitiesAutoStartHigh disabled Auto-start live activities for high-severity (not just critical) incidents
lt.settings.liveActivitiesSessionEnabled enabled Session live activities for active remote sessions
lt.settings.liveActivitiesShowFullDetails disabled (redacted) Show full details on lock screen instead of redacted summary

Incident quick actions from Live Activities require local device-owner authentication before issuing the status mutation.

Agent Settings

Docker Endpoint

Key Env Var Accepted Forms
docker_endpoint LABTETHER_DOCKER_SOCKET Absolute unix socket path, unix:// URI, or http(s)://host:port for remote Docker API. Invalid values fall back to /var/run/docker.sock.

Low-Power Profile (Linux)

Key Env Var Default
Low-power mode LABTETHER_LOW_POWER_MODE false

When enabled, applies these defaults (explicit env values still override):

Setting Low-Power Default
AGENT_COLLECT_INTERVAL 30s
AGENT_HEARTBEAT_INTERVAL 120s
LABTETHER_DOCKER_DISCOVERY_INTERVAL 5m
LABTETHER_SERVICES_DISCOVERY_INTERVAL 10m
LABTETHER_SERVICES_DISCOVERY_PORT_SCAN_ENABLED false
LABTETHER_SERVICES_DISCOVERY_PORT_SCAN_INCLUDE_LISTENING false
LABTETHER_LOG_STREAM_ENABLED false

Service Discovery Fleet Defaults

Location: Settings -> Service Discovery Defaults or Settings -> Advanced Settings -> services. Keys: services.discovery_default_*.

Discovery Type Default
Docker discovery enabled
Proxy API discovery (Traefik, Caddy, Nginx Proxy Manager) enabled
Local host port scan enabled
LAN CIDR scan disabled

Per-node overrides are available at Node -> Agent Settings -> Service Discovery Policy (keys: services_discovery_*). Agent restart required after changes.

Agent CLI Commands

Command Description
labtether-agent settings show Display current agent settings
labtether-agent settings set Update an agent setting
labtether-agent settings wizard Interactive settings wizard
labtether-agent settings test docker Test Docker endpoint connectivity
labtether-agent identity show Display agent identity
labtether-agent update self [--force] Self-update the agent binary