Skip to content

⚙️ 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 ​

Showing 25 of 25 environment variables
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.

Default Value:(Empty - Plaintext)
Data Type:Base64 (32 bytes)
Generate with OpenSSL:
openssl rand -base64 32
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.

Default Value:(Empty - Disabled)
Data Type:Hex / String
Generate with OpenSSL:
openssl rand -hex 24
DISABLE_SIGNUPSOptionalSecurity

When 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.

Default Value:false
Data Type:Boolean
PORTOptionalNetwork

The internal HTTP/HTTPS port the Express server binds inside the container. Set to 6565 during local non-container development.

Default Value:6464
Data Type:Integer
HOSTOptionalNetwork

Network 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.

Default Value:0.0.0.0
Data Type:String
NODE_ENVOptionalNetwork

Application execution mode (production or development). Controls debug telemetry, error stack traces, and static asset caching.

Default Value:production
Data Type:String
TRUST_PROXYOptionalNetwork

Enables 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.

Default Value:false
Data Type:Boolean
CORS_ORIGINOptionalNetwork

Permitted 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.

Default Value:(Unset - Private LAN auto)
Data Type:Comma-separated URLs
TLS_ENABLEDOptionalTLS

Enables 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.

Default Value:false
Data Type:Boolean
TLS_CERT_PATHOptionalTLS

Absolute container path to Bring-Your-Own (BYO) public SSL/TLS certificate in PEM format. Must be paired with TLS_KEY_PATH.

Default Value:(Empty)
Data Type:File Path
TLS_KEY_PATHOptionalTLS

Absolute container path to Bring-Your-Own (BYO) private SSL/TLS key in PEM format. Must be paired with TLS_CERT_PATH.

Default Value:(Empty)
Data Type:File Path
ENFORCE_HTTPSOptionalTLS

Enforces automatic redirection of plain HTTP requests to HTTPS using X-Forwarded-Proto (when TRUST_PROXY=true) or direct connection state.

Default Value:false
Data Type:Boolean
HTTPS_PORTOptionalTLS

Destination HTTPS port used when redirecting HTTP requests under ENFORCE_HTTPS=true.

Default Value:4647
Data Type:Integer
DATA_DIRRequiredStorage

Persistent storage root holding db.sqlite, audit.sqlite, certs/, and instance.key. In Docker, this path must be bound to a persistent host volume.

Default Value:/app/data
Data Type:Directory Path
PUIDOptionalStorage

Host user ID mapped inside docker-entrypoint.sh to grant proper filesystem ownership of mounted data volumes without running as root.

Default Value:1000 (99 on Unraid)
Data Type:Integer
PGIDOptionalStorage

Host group ID mapped inside docker-entrypoint.sh to grant proper filesystem ownership of mounted data volumes.

Default Value:1000 (100 on Unraid)
Data Type:Integer
ATTACHMENT_MAX_MBOptionalStorage

Maximum allowable size in megabytes for a single encrypted file attachment. Uploads exceeding this threshold terminate with HTTP 413 Payload Too Large.

Default Value:500
Data Type:Integer (MB)
GROTTO_QUOTA_MBOptionalStorage

Total cumulative attachment ciphertext quota in megabytes allocated per vault owner. Further uploads are rejected once grotto storage reaches this limit.

Default Value:1000
Data Type:Integer (MB)
TOKEN_TTL_DEFAULTOptionalAdmin

Default expiration duration for issued api- user session tokens. Accepts 30m, 12h, 24h, 7d, never, or a numeric value in minutes.

Default Value:1440 (24h)
Data Type:String / Integer
AUTH_RATE_WINDOWOptionalRate Limits

Sliding window in milliseconds used to track and limit repeated failed authentication attempts.

Default Value:900000 (15m)
Data Type:Integer (ms)
AUTH_RATE_LIMITOptionalRate Limits

Maximum number of failed login attempts permitted per client IP within AUTH_RATE_WINDOW before IP is temporarily locked out.

Default Value:10
Data Type:Integer
API_RATE_WINDOWOptionalRate Limits

Sliding window in milliseconds for general API endpoint request rate limiting.

Default Value:60000 (1m)
Data Type:Integer (ms)
API_RATE_LIMITOptionalRate Limits

Maximum total requests permitted per client IP within API_RATE_WINDOW before returning HTTP 429 Too Many Requests.

Default Value:100
Data Type:Integer
VITE_API_URLOptionalFrontend

Base URL for API requests made by the frontend. In standard Docker deployments, leave unset to utilize same-origin relative paths.

Default Value:(Unset - Same Origin)
Data Type:URL
VITE_SHELLCRYPTION_ENABLEDOptionalFrontend

Controls client-side resting encryption. Keep true to ensure master secrets are encrypted with AES-GCM-256 before leaving browser memory.

Default Value:true
Data Type:Boolean

🔑 Core Cryptography & Identity Invariants ​

1. Master Database Key (DB_ENCRYPTION_KEY) ​

bash
# Generate a cryptographically random 256-bit Base64 key
openssl rand -base64 32

The DB_ENCRYPTION_KEY governs two distinct defense-in-depth layers:

  1. Layer 2 (Per-Row Metadata Encryption): Encrypts vault item titles, usernames, URLs, categories, custom fields, tags, and attachment metadata with AES-256-GCM.
  2. Layer 3 (SQLCipher Whole-DB Encryption): Encrypts the underlying db.sqlite SQLite 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) ​

bash
# Generate a secure administrative token
openssl rand -hex 24

Guards 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:

ini
TRUST_PROXY=true

tells 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.sqlite log physical remote IPs.

Cross-Origin Resource Sharing (CORS_ORIGIN) ​

ShellGuard adopts a zero-friction security default for LAN setups:

  • When CORS_ORIGIN is unset, the server automatically permits requests from localhost, 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.pem and $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:

yaml
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 between 1 and 2000 MB. Pre-stream Content-Length validation fast-rejects oversized uploads with HTTP 413 Payload Too Large before streaming ciphertext into server memory.
  • GROTTO_QUOTA_MB (Default: 1000): Cumulative storage quota per user, validated and clamped between 1 and 100,000 MB. Fast-rejects with HTTP 413 if currentUsage + Content-Length exceeds the grotto quota. Startup diagnostics emit a warning if ATTACHMENT_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:

yaml
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

Sovereign Zero-Knowledge Secrets Vault. Released under AGPL-3.0. • Privacy Policy