⚙️ Docker Environment Variables Reference
ShellGuard is distributed as a single unified container image (ghcr.io/clawstackstudios/shellguard). All runtime configurations—including cryptographic keys, storage directories, network bindings, and rate limit ceilings—are injected via environment variables.
Use the interactive catalog below to filter by category, search specific parameters, or copy variable names and ready-to-paste assignments directly to your clipboard.
🎛️ Interactive Variable Catalog
DB_ENCRYPTION_KEYRecommendedSecurity 🛡️ Sensitive Key Governs Layer 2 metadata-at-rest encryption (AES-256-GCM) and Layer 3 SQLCipher whole-database encryption. When unset, vault secret blobs are still client-encrypted, but database metadata (titles, usernames, URLs) remains unencrypted at rest.
ADMIN_TOKENRecommendedSecurity 🛡️ Sensitive Key Authentication token for the SuperLobster control plane at /superlobster. When unset, all admin routes return 503. This token manages telemetry, snapshots, and user administration, but NEVER decrypts vault secrets.
DISABLE_SIGNUPSOptionalSecurityWhen true, closes open registration. Creating a new identity requires a single-use SuperLobster invite token (?invite=inv_...). Genesis User #1 is immune and can always initialize.
PORTOptionalNetworkThe internal HTTP/HTTPS port the Express server binds inside the container. Set to 6565 during local non-container development.
HOSTOptionalNetworkNetwork interface binding. Use 0.0.0.0 to listen on all interfaces or 127.0.0.1 for loopback isolation behind a local reverse proxy.
NODE_ENVOptionalNetworkApplication execution mode (production or development). Controls debug telemetry, error stack traces, and static asset caching.
TRUST_PROXYOptionalNetworkEnables Express trust proxy. Mandatory when running behind Nginx, Caddy, Traefik, or Cloudflare Tunnel to accurately extract client IP addresses for rate limiting and audit logging.
CORS_ORIGINOptionalNetworkPermitted browser origins for API requests. Leaving unset automatically permits localhost and RFC 1918 / CGNAT private ranges. Set to your public domain (e.g. https://vault.example.com) for reverse-proxied production deployments.
TLS_ENABLEDOptionalTLSEnables native HTTPS. On first boot, automatically generates a 10-year EC P-256 self-signed certificate in $DATA_DIR/certs/ covering localhost and all local LAN interfaces.
TLS_CERT_PATHOptionalTLSAbsolute container path to Bring-Your-Own (BYO) public SSL/TLS certificate in PEM format. Must be paired with TLS_KEY_PATH.
TLS_KEY_PATHOptionalTLSAbsolute container path to Bring-Your-Own (BYO) private SSL/TLS key in PEM format. Must be paired with TLS_CERT_PATH.
ENFORCE_HTTPSOptionalTLSEnforces automatic redirection of plain HTTP requests to HTTPS using X-Forwarded-Proto (when TRUST_PROXY=true) or direct connection state.
HTTPS_PORTOptionalTLSDestination HTTPS port used when redirecting HTTP requests under ENFORCE_HTTPS=true.
DATA_DIRRequiredStoragePersistent storage root holding db.sqlite, audit.sqlite, certs/, and instance.key. In Docker, this path must be bound to a persistent host volume.
PUIDOptionalStorageHost user ID mapped inside docker-entrypoint.sh to grant proper filesystem ownership of mounted data volumes without running as root.
PGIDOptionalStorageHost group ID mapped inside docker-entrypoint.sh to grant proper filesystem ownership of mounted data volumes.
ATTACHMENT_MAX_MBOptionalStorageMaximum allowable size in megabytes for a single encrypted file attachment. Uploads exceeding this threshold terminate with HTTP 413 Payload Too Large.
GROTTO_QUOTA_MBOptionalStorageTotal cumulative attachment ciphertext quota in megabytes allocated per vault owner. Further uploads are rejected once grotto storage reaches this limit.
TOKEN_TTL_DEFAULTOptionalAdminDefault expiration duration for issued api- user session tokens. Accepts 30m, 12h, 24h, 7d, never, or a numeric value in minutes.
AUTH_RATE_WINDOWOptionalRate LimitsSliding window in milliseconds used to track and limit repeated failed authentication attempts.
AUTH_RATE_LIMITOptionalRate LimitsMaximum number of failed login attempts permitted per client IP within AUTH_RATE_WINDOW before IP is temporarily locked out.
API_RATE_WINDOWOptionalRate LimitsSliding window in milliseconds for general API endpoint request rate limiting.
API_RATE_LIMITOptionalRate LimitsMaximum total requests permitted per client IP within API_RATE_WINDOW before returning HTTP 429 Too Many Requests.
VITE_API_URLOptionalFrontendBase URL for API requests made by the frontend. In standard Docker deployments, leave unset to utilize same-origin relative paths.
VITE_SHELLCRYPTION_ENABLEDOptionalFrontendControls client-side resting encryption. Keep true to ensure master secrets are encrypted with AES-GCM-256 before leaving browser memory.
🔑 Core Cryptography & Identity Invariants
1. Master Database Key (DB_ENCRYPTION_KEY)
# Generate a cryptographically random 256-bit Base64 key
openssl rand -base64 32The DB_ENCRYPTION_KEY governs two distinct defense-in-depth layers:
- Layer 2 (Per-Row Metadata Encryption): Encrypts vault item titles, usernames, URLs, categories, custom fields, tags, and attachment metadata with AES-256-GCM.
- Layer 3 (SQLCipher Whole-DB Encryption): Encrypts the underlying
db.sqliteSQLite database file at rest on disk.
IMPORTANT
DB_ENCRYPTION_KEY accepts both standard Base64 (+/=) and Base64URL (-_) encodings. It must decode to at least 32 bytes (256 bits) of cryptographic entropy. Client secret payloads are always encrypted client-side with ShellCryption™ before leaving the browser, regardless of whether DB_ENCRYPTION_KEY is configured. However, leaving DB_ENCRYPTION_KEY unset stores vault item titles and categories in plaintext on disk. Setting this variable is strongly advised for all production deployments.
2. SuperLobster Control Plane Token (ADMIN_TOKEN)
# Generate a secure administrative token
openssl rand -hex 24Guards the SuperLobster administrator panel at /superlobster. When unset, or configured with fewer than 16 characters or trivial passwords (admin, true, 123456), all administrative routes return HTTP 503 Service Unavailable and the startup diagnostic banner logs a configuration warning.
NOTE
ADMIN_TOKEN has zero decryption authority over user secrets. It is strictly scoped to system health inspection, scheduled database snapshots, audit log export, and identity lifecycle management.
3. Public Registration Gate (DISABLE_SIGNUPS)
By default (false), any user who accesses the ShellGuard instance can create a new vault identity. In multi-user self-hosted environments or public internet deployments, setting DISABLE_SIGNUPS=true (or 1, yes) locks down identity creation. New identities then require a single-use invite token (?invite=inv_...) generated by an administrator inside the SuperLobster panel.
WARNING
Catch-22 Lockout Alert: If DISABLE_SIGNUPS=true is enabled while ADMIN_TOKEN is unset or invalid, Genesis User #1 can hatch normally, but subsequent users cannot be invited because the administrative invite generator is sealed. Ensure a valid ADMIN_TOKEN is configured alongside DISABLE_SIGNUPS.
🌐 Networking, Reverse Proxies & CORS
Reverse Proxy Detection (TRUST_PROXY)
When ShellGuard runs behind a reverse proxy (e.g. Nginx, Caddy, Traefik, NPM, or Cloudflare Tunnel), the incoming TCP connection terminates at the proxy. Setting:
TRUST_PROXY=truetells Express to inspect the X-Forwarded-For and X-Forwarded-Proto request headers, ensuring that:
- Brute-force rate limiters track the actual client IP rather than the reverse proxy's internal gateway IP.
- HTTPS redirects correctly recognize SSL termination at the proxy edge.
- Audit records in
audit.sqlitelog physical remote IPs.
Cross-Origin Resource Sharing (CORS_ORIGIN)
ShellGuard adopts a zero-friction security default for LAN setups:
- When
CORS_ORIGINis unset, the server automatically permits requests fromlocalhost,127.0.0.1, RFC 1918 private subnets (192.168.0.0/16,10.0.0.0/8,172.16.0.0/12), and Carrier-Grade NAT / Tailscale ranges (100.64.0.0/10). - For public domains, set
CORS_ORIGIN=https://vault.yourdomain.com(or comma-separated origins) to restrict API calls to trusted frontends.
🔒 Native HTTPS & Bring-Your-Own TLS
ShellGuard supports native HTTPS without requiring an external reverse proxy:
Self-Signed Frictionless TLS (TLS_ENABLED=true)
When TLS_ENABLED=true is specified without external certificate paths:
- ShellGuard generates a 10-year EC P-256 certificate and private key on first startup and writes them to
$DATA_DIR/certs/cert.pemand$DATA_DIR/certs/key.pem. - Subject Alternative Names (SANs) include
localhost,127.0.0.1, and all detected host LAN IPs. - Docker health checks automatically bypass certificate validation via
wget --no-check-certificate.
Bring-Your-Own Certificates (TLS_CERT_PATH & TLS_KEY_PATH)
Mount your custom PEM certificate and private key into the container and provide their absolute container paths:
environment:
- TLS_CERT_PATH=/app/data/certs/vault.crt
- TLS_KEY_PATH=/app/data/certs/vault.key💾 Storage, Permissions & Quotas
Container User Mapping (PUID & PGID)
To prevent permission conflicts when mounting host directories into the container, ShellGuard features an entrypoint privilege-drop script (docker-entrypoint.sh). It remaps the internal node user to match your host user and group IDs:
- Standard Linux / Docker:
PUID=1000,PGID=1000 - Unraid:
PUID=99,PGID=100
Attachment Storage Ceilings & Pre-Stream Quota Protection
ShellGuard stores encrypted file attachments directly as raw ciphertext BLOBs in SQLite:
ATTACHMENT_MAX_MB(Default:500): Hard per-file ceiling, validated and clamped between1and2000MB. Pre-streamContent-Lengthvalidation fast-rejects oversized uploads with HTTP413 Payload Too Largebefore streaming ciphertext into server memory.GROTTO_QUOTA_MB(Default:1000): Cumulative storage quota per user, validated and clamped between1and100,000MB. Fast-rejects with HTTP413ifcurrentUsage + Content-Lengthexceeds the grotto quota. Startup diagnostics emit a warning ifATTACHMENT_MAX_MB > GROTTO_QUOTA_MB.
Frontend Variables Notice (VITE_*)
VITE_API_URL and VITE_SHELLCRYPTION_ENABLED are frontend parameters compiled into client static assets at build time (npm run build). Passing them as runtime environment variables to a production container has no effect on client bundles unless the frontend image is rebuilt. When VITE_SHELLCRYPTION_ENABLED=false is compiled into a build, the client renders a persistent high-visibility red warning banner across all views.
📋 Production Compose Blueprint
A complete docker-compose.yml leveraging standard production variables:
services:
shellguard:
image: ghcr.io/clawstackstudios/shellguard:latest
container_name: shellguard
restart: unless-stopped
ports:
- "6464:6464"
volumes:
- ./data:/app/data
environment:
# Core Identity & Encryption
- NODE_ENV=production
- PORT=6464
- DATA_DIR=/app/data
- DB_ENCRYPTION_KEY=YOUR_GENERATED_BASE64_KEY
- ADMIN_TOKEN=YOUR_GENERATED_ADMIN_HEX
- DISABLE_SIGNUPS=false
# Reverse Proxy & Networking
- TRUST_PROXY=true
- CORS_ORIGIN=https://vault.example.com
# Permissions (Unraid: PUID=99, PGID=100)
- PUID=1000
- PGID=1000
# Storage & Quotas
- ATTACHMENT_MAX_MB=500
- GROTTO_QUOTA_MB=2000
- TOKEN_TTL_DEFAULT=24h
healthcheck:
test: ["CMD", "wget", "-qO-", "http://localhost:6464/api/health"]
interval: 15s
timeout: 10s
retries: 5
start_period: 15s🔗 Related Documentation
- Docker & Compose Stacks — Deployment walkthrough and container lifecycle.
- First-Class HTTPS & TLS — In-depth guide on native TLS and reverse proxy architectures.
- Unraid Community Apps — One-click template deployment for Unraid storage servers.
- Database Blueprint Schema — Relational schema and encryption primitives.