Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Shashank-H/gaiter-gaurd/llms.txt

Use this file to discover all available pages before exploring further.

​
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 hoursExample:
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

# 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

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us