Configuration Reference

Complete environment variable reference for GaiterGuard backend configuration

Overview

GaiterGuard is configured entirely through environment variables. All variables are validated at startup, and the server will refuse to start if required variables are missing or invalid.

Environment File

Create a .env file in the backend/ directory:

cp backend/.env.example backend/.env

Never commit .env files to version control. The .env.example file contains safe defaults for local development only.

Required Variables

These variables must be set or the backend will not start.

DATABASE_URL · string · required

PostgreSQL connection string in the format:

postgres://username:password@host:port/database

Example:

DATABASE_URL=postgres://pglocal:pglocal-pass@localhost:5432/gaiterguard

Docker Compose:

DATABASE_URL=postgres://pglocal:pglocal-pass@db:5432/gaiterguard

Use the service name db as the host when running in Docker Compose.

JWT_SECRET · string · required

Secret key for signing JWT access and refresh tokens. Must be a long, random string.

Security: Use a cryptographically secure random string of at least 32 characters.

Generate:

openssl rand -base64 32

Example:

JWT_SECRET=8vQ3m6P9xR2nL5tY7jK4wZ1bN0cH8fS6

Never use predictable values like "secret" or "dev-secret" in production.

ENCRYPTION_SECRET · string · required

Master key for encrypting service credentials in the vault. Used with AES-256-GCM.

Security:

• Must be at least 32 characters long (enforced)
• Use a cryptographically secure random string
• If changed, existing credentials become unreadable

Generate:

openssl rand -base64 48 | cut -c1-32

Example:

ENCRYPTION_SECRET=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Changing this value will make all existing encrypted credentials unreadable. Back up your database before rotating.

LLM_BASE_URL · string · required

Base URL for the LLM API used for risk assessment. Must be OpenAI-compatible.

Supported providers:

• OpenAI: https://api.openai.com/v1
• Azure OpenAI: https://{resource}.openai.azure.com/openai/deployments/{deployment}
• Local models (Ollama): http://localhost:11434/v1
• Any OpenAI-compatible endpoint

Example:

LLM_BASE_URL=https://api.openai.com/v1

LLM_API_KEY · string · required

API key for authenticating with the LLM service.

Example:

LLM_API_KEY=sk-proj-abc123...

For local Ollama instances, you can use a placeholder value like "ollama" since authentication is not required.

Optional Variables

These variables have sensible defaults but can be customized.

PORT · number · default: "3000"

Port the backend API server listens on.

Example:

PORT=3000

JWT_ACCESS_EXPIRY · string · default: "15m"

Access token expiration time. Accepts time units: s (seconds), m (minutes), h (hours), d (days).

Recommended: 15 minutes to 1 hour for security.

Examples:

JWT_ACCESS_EXPIRY=15m   # 15 minutes
JWT_ACCESS_EXPIRY=1h    # 1 hour
JWT_ACCESS_EXPIRY=30s   # 30 seconds (for testing)

JWT_REFRESH_EXPIRY · string · default: "7d"

Refresh token expiration time. Users must log in again after this period.

Recommended: 7 to 30 days.

Examples:

JWT_REFRESH_EXPIRY=7d   # 7 days
JWT_REFRESH_EXPIRY=30d  # 30 days
JWT_REFRESH_EXPIRY=24h  # 24 hours

ENCRYPTION_SALT · string · default: "gaiter-guard-salt-v1"

Salt value used in credential encryption key derivation. Change this to rotate the encryption scheme.

Example:

ENCRYPTION_SALT=gaiter-guard-salt-v1

Changing this requires re-encrypting all credentials. Use the same value across backend instances.

LLM_MODEL · string · default: "gpt-4o-mini"

LLM model name to use for risk assessment.

Recommended models:

• gpt-4o-mini - Fast, cost-effective, good accuracy
• gpt-4o - Highest accuracy, more expensive
• gpt-3.5-turbo - Faster, lower cost, slightly less accurate

Example:

LLM_MODEL=gpt-4o-mini

LLM_TIMEOUT_MS · number · default: "10000"

Timeout for LLM API requests in milliseconds.

Recommended: 10000-30000 (10-30 seconds)

Example:

LLM_TIMEOUT_MS=10000  # 10 seconds

If risk assessment times out, the request is rejected as a safety measure.

RISK_THRESHOLD · number · default: "0.5"

Risk score threshold (0.0 to 1.0) above which requests require human approval.

• 0.0 - Block nothing (all requests pass)
• 0.3 - Block high-risk operations (PUT, DELETE)
• 0.5 - Balanced (recommended)
• 0.7 - Aggressive (blocks most POST/PATCH)
• 1.0 - Block everything

Example:

RISK_THRESHOLD=0.5

Start with 0.5 and adjust based on false positive/negative rates. Lower values are more permissive.

APPROVAL_EXECUTE_TTL_HOURS · number · default: "1"

Hours after approval before the execution window expires. Agents must execute approved requests within this time.

Recommended: 1-24 hours

Example:

APPROVAL_EXECUTE_TTL_HOURS=1  # 1 hour

After expiry, the action transitions to EXPIRED status. Agents must resubmit via POST /proxy.

NODE_ENV · string · default: "development"

Node.js environment mode. Set to production in production deployments.

Values:

• development - Enables debug logging
• production - Production optimizations, reduced logging

Example:

NODE_ENV=production

Example Configurations

Local Development

# Backend runs on host machine, PostgreSQL in Docker
DATABASE_URL=postgres://pglocal:pglocal-pass@localhost:5432/gaiterguard
PORT=3000
JWT_SECRET=dev-secret-change-in-production
JWT_ACCESS_EXPIRY=15m
JWT_REFRESH_EXPIRY=7d
ENCRYPTION_SECRET=dev-encryption-secret-32-characters
ENCRYPTION_SALT=gaiter-guard-salt-v1
LLM_BASE_URL=https://api.openai.com/v1
LLM_API_KEY=sk-proj-your-key-here
LLM_MODEL=gpt-4o-mini
LLM_TIMEOUT_MS=10000
RISK_THRESHOLD=0.5
APPROVAL_EXECUTE_TTL_HOURS=1

# All services in Docker network
DATABASE_URL=postgres://pglocal:pglocal-pass@db:5432/gaiterguard
PORT=3000
JWT_SECRET=8vQ3m6P9xR2nL5tY7jK4wZ1bN0cH8fS6dG9hJ2kL5mN8pQ1rT4uV7xY0zA3bC6e
JWT_ACCESS_EXPIRY=15m
JWT_REFRESH_EXPIRY=30d
ENCRYPTION_SECRET=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6
ENCRYPTION_SALT=gaiter-guard-salt-v1
LLM_BASE_URL=https://api.openai.com/v1
LLM_API_KEY=sk-proj-your-key-here
LLM_MODEL=gpt-4o-mini
LLM_TIMEOUT_MS=15000
RISK_THRESHOLD=0.5
APPROVAL_EXECUTE_TTL_HOURS=2
NODE_ENV=production

# Conservative risk threshold, short TTLs
DATABASE_URL=postgres://pglocal:pglocal-pass@db:5432/gaiterguard
PORT=3000
JWT_SECRET=<generate-with-openssl-rand>
JWT_ACCESS_EXPIRY=5m
JWT_REFRESH_EXPIRY=24h
ENCRYPTION_SECRET=<generate-with-openssl-rand>
ENCRYPTION_SALT=gaiter-guard-salt-v1
LLM_BASE_URL=https://api.openai.com/v1
LLM_API_KEY=sk-proj-your-key-here
LLM_MODEL=gpt-4o
LLM_TIMEOUT_MS=20000
RISK_THRESHOLD=0.3
APPROVAL_EXECUTE_TTL_HOURS=1
NODE_ENV=production

Validation Rules

GaiterGuard validates all environment variables at startup (see backend/src/config/env.ts:1):

• DATABASE_URL: Must be a valid PostgreSQL connection string
• JWT_SECRET: Required, no minimum length (but use 32+ chars)
• ENCRYPTION_SECRET: Must be at least 32 characters
• RISK_THRESHOLD: Must be a number between 0.0 and 1.0
• PORT: Must be a valid integer
• LLM_TIMEOUT_MS: Must be a valid integer
• APPROVAL_EXECUTE_TTL_HOURS: Must be a valid integer

If validation fails, the backend will log the error and exit.

Security Best Practices

1. Use strong secrets

   Generate secrets with cryptographic tools:

   openssl rand -base64 32  # JWT_SECRET
   openssl rand -base64 48 | cut -c1-32  # ENCRYPTION_SECRET
   
2. Restrict file permissions

   Protect your .env file:

   chmod 600 backend/.env
   
3. Never commit secrets

   Ensure .env is in .gitignore:

   echo "backend/.env" >> .gitignore
   
4. Rotate credentials regularly

   • Rotate JWT_SECRET monthly
   • Rotate ENCRYPTION_SECRET quarterly (requires re-encrypting credentials)
   • Use secret management tools (AWS Secrets Manager, HashiCorp Vault)

Next Steps

Deployment

Deploy to production with Docker Compose

Agent Integration

Integrate AI agents with the gateway