Configuration - Guardway

Complete reference for configuring Guardway Gateway and all its components.

Environment Variables

Server Configuration

PORT

number

HTTP server port. Default: 8000.

HOST

string

HTTP server host. Default: 0.0.0.0.

NODE_ENV

string

Environment: development, production, test. Default: development.

LOG_LEVEL

string

Log level: trace, debug, info, warn, error, fatal. Default: info.

CORS_ORIGIN

string

CORS allowed origins (comma-separated). Default: *.

GATEWAY_REQUEST_TIMEOUT_MS

number

Request timeout in milliseconds. Default: 30000.

GATEWAY_COMPLETION_TIMEOUT_MS

number

LLM completion timeout in milliseconds. Default: 120000.

Security Configuration

All security variables below contain sensitive credentials. Never commit them to version control. Use environment variables, secret managers, or encrypted .env files in production.

AGSEC_MASTER_KEY

string

required

Master key for admin access. Must start with sk-master-.

GATEWAY_API_KEY

string

required

Internal API key for admin UI. Must start with sk-internal-.

CONFIG_ENCRYPTION_KEY

string

required

AES-256 encryption key for secrets (32 bytes).

SESSION_SECRET

string

HMAC secret for session tokens (generated if not set).

Example:

AGSEC_MASTER_KEY=sk-master-d8f7a6b5c4e3f2a1
GATEWAY_API_KEY=sk-internal-a1b2c3d4e5f6g7h8
CONFIG_ENCRYPTION_KEY=0123456789abcdef0123456789abcdef

Provider API Keys

At least one provider API key is required for the gateway to function.

OPENAI_API_KEY

string

OpenAI API key. Get from platform.openai.com/api-keys.

ANTHROPIC_API_KEY

string

Anthropic API key. Get from console.anthropic.com/settings/keys.

GROQ_API_KEY

string

Groq API key. Get from console.groq.com/keys.

GOOGLE_API_KEY

string

Google Gemini API key. Get from makersuite.google.com/app/apikey.

MISTRAL_API_KEY

string

Mistral API key. Get from console.mistral.ai/api-keys.

COHERE_API_KEY

string

Cohere API key. Get from dashboard.cohere.com/api-keys.

DEEPSEEK_API_KEY

string

Deepseek API key. Get from platform.deepseek.com/api_keys.

FIREWORKS_API_KEY

string

Fireworks API key. Get from fireworks.ai/api-keys.

HUGGINGFACE_API_KEY

string

HuggingFace API key. Get from huggingface.co/settings/tokens.

TOGETHER_API_KEY

string

Together API key. Get from api.together.xyz/settings/api-keys.

PERPLEXITY_API_KEY

string

Perplexity API key. Get from perplexity.ai/settings/api.

OPENROUTER_API_KEY

string

OpenRouter API key. Get from openrouter.ai/keys.

XAI_API_KEY

string

xAI (Grok) API key. Get from console.x.ai.

VOYAGE_API_KEY

string

Voyage API key. Get from dash.voyageai.com/api-keys.

ASSEMBLYAI_API_KEY

string

AssemblyAI API key. Get from assemblyai.com/app/account.

ELEVENLABS_API_KEY

string

ElevenLabs API key. Get from elevenlabs.io/app/settings/api-keys.

FAL_KEY

string

Fal API key. Get from fal.ai/dashboard/keys.

Cloud Provider Configuration

AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...

Redis Configuration

REDIS_URL

string

Redis connection URL. Default: redis://localhost:6379.

REDIS_PASSWORD

string

Redis password (if auth enabled).

REDIS_DB

number

Redis database number. Default: 0.

REDIS_TLS

boolean

Enable TLS for Redis connection. Default: false.

REDIS_KEY_PREFIX

string

Key prefix for all Redis keys. Default: gw:.

Examples:

REDIS_URL=redis://localhost:6379

PostgreSQL Configuration

POSTGRES_HOST

string

PostgreSQL host. Default: localhost.

POSTGRES_PORT

number

PostgreSQL port. Default: 5432.

POSTGRES_DB

string

Database name. Default: agsec.

POSTGRES_USER

string

Database user. Default: agsec.

POSTGRES_PASSWORD

string

Database password.

POSTGRES_SSL

boolean

Enable SSL connection. Default: false.

Example:

POSTGRES_HOST=postgres.example.com
POSTGRES_PORT=5432
POSTGRES_DB=agsec_prod
POSTGRES_USER=agsec_user
POSTGRES_PASSWORD=secure_password
POSTGRES_SSL=true

Rate Limiting Configuration

RATE_LIMIT_ENABLED

boolean

Enable rate limiting. Default: true.

RATE_LIMIT_REQUESTS_PER_MINUTE

number

Default requests/minute per API key. Default: 100.

RATE_LIMIT_TOKENS_PER_MINUTE

number

Default tokens/minute per API key. Default: 100000.

RATE_LIMIT_WINDOW_MS

number

Rate limit window (1 minute). Default: 60000.

Example:

RATE_LIMIT_ENABLED=true
RATE_LIMIT_REQUESTS_PER_MINUTE=1000
RATE_LIMIT_TOKENS_PER_MINUTE=1000000

Caching Configuration

CACHE_ENABLED

boolean

Enable caching. Default: true.

CACHE_TYPE

string

Cache backend: memory, redis. Default: memory.

CACHE_TTL

number

Cache TTL in seconds. Default: 3600.

CACHE_MAX_SIZE

number

Max entries for in-memory cache. Default: 10000.

CACHE_COMPLETIONS

boolean

Cache completion responses. Default: true.

CACHE_EMBEDDINGS

boolean

Cache embedding responses. Default: true.

Example:

CACHE_ENABLED=true
CACHE_TYPE=redis
CACHE_TTL=7200
CACHE_MAX_SIZE=50000

OpenTelemetry Configuration

OTEL_ENABLED

boolean

Enable OpenTelemetry tracing. Default: false.

OTEL_SERVICE_NAME

string

Service name in traces. Default: aigw-gateway.

OTEL_EXPORTER_OTLP_ENDPOINT

string

OTLP endpoint. Default: http://localhost:4318.

OTEL_EXPORTER_OTLP_PROTOCOL

string

OTLP protocol. Default: http/protobuf.

OTEL_LOG_LEVEL

string

OpenTelemetry log level. Default: info.

Examples:

OTEL_ENABLED=1
OTEL_SERVICE_NAME=aigw-gateway
OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4318

MCP Configuration

MCP_RUNTIME_URL

string

MCP runtime service URL. Default: http://localhost:8931/mcp.

MCP_SESSION_TTL_MS

number

MCP session TTL (25 seconds). Default: 25000.

MCP_REQUEST_TIMEOUT_MS

number

MCP request timeout. Default: 30000.

MCP_MAX_REQUEST_SIZE

number

Max request size (512KB). Default: 524288.

Example:

MCP_RUNTIME_URL=http://mcp-runtime:8931/mcp
MCP_SESSION_TTL_MS=30000
MCP_REQUEST_TIMEOUT_MS=60000

Guardrails Configuration

Guardrails add latency to every request. For latency-sensitive workloads, consider setting higher thresholds or using regex/pattern detection methods rather than slm, and apply guardrails only to the request direction.

GUARDRAILS_ENABLED

boolean

Enable guardrails system. Default: true.

ORIONFENCE_API_URL

string

OrionFence API endpoint.

ORIONFENCE_DEFAULT_MODEL

string

Default OrionFence model. Default: guardway/slm-shield-v1.

ORIONFENCE_DEFAULT_THRESHOLD

number

Default confidence threshold. Default: 0.5.

ORIONFENCE_TIMEOUT_MS

number

OrionFence API timeout. Default: 5000.

Example:

GUARDRAILS_ENABLED=true
ORIONFENCE_API_URL=https://api.orionfence.com/v1
ORIONFENCE_DEFAULT_MODEL=guardway/slm-shield-v1
ORIONFENCE_DEFAULT_THRESHOLD=0.7

Admin UI Configuration

NEXT_PUBLIC_GATEWAY_URL

string

Gateway API URL (for browser). Default: http://localhost:8000.

NEXT_PUBLIC_APP_NAME

string

Application name. Default: Guardway Gateway.

NEXT_PUBLIC_APP_VERSION

string

Application version. Default: 1.0.0.

Example:

NEXT_PUBLIC_GATEWAY_URL=https://gateway.example.com
NEXT_PUBLIC_APP_NAME=My AI Gateway
NEXT_PUBLIC_APP_VERSION=2.0.0

Provider Configuration

Providers can be configured via Admin UI or API.

Adding a Provider (API)

curl -X POST http://localhost:8000/providers \
  -H "Authorization: Bearer ${AGSEC_MASTER_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "providerId": "openai",
    "providerName": "OpenAI",
    "apiKey": "sk-...",
    "config": {
      "baseURL": "https://api.openai.com/v1",
      "organization": "org-...",
      "customHeaders": {
        "X-Custom-Header": "value"
      }
    }
  }'

Provider Configuration Schema

interface ProviderConfig {
  providerId: string        // Unique provider ID
  providerName: string      // Display name
  apiKey: string            // API key (encrypted at rest)
  config: {
    baseURL?: string        // Custom API base URL
    organization?: string   // Organization ID (OpenAI)
    project?: string        // Project ID (OpenAI)
    customHeaders?: Record<string, string>  // Custom headers
    timeout?: number        // Request timeout (ms)
    maxRetries?: number     // Max retry attempts
    defaultModel?: string   // Default model for provider
  }
}

Provider-Specific Configuration

{
  "providerId": "openai",
  "providerName": "OpenAI",
  "apiKey": "sk-...",
  "config": {
    "organization": "org-...",
    "project": "proj_...",
    "baseURL": "https://api.openai.com/v1"
  }
}

Routing Configuration

Routing Rules

Routing rules determine which provider handles which requests. Rule Schema:

interface RoutingRule {
  id: string
  priority: number          // Lower = higher priority
  pattern: {
    type: 'equals' | 'startsWith' | 'contains'
    value: string          // Model name pattern
  }
  providerId: string       // Target provider
  enabled: boolean
  budgetLimit?: {          // Optional budget limit for this rule
    amount: number         // USD
    window: 'hour' | 'day' | 'month'
  }
  tokenLimit?: {           // Optional token limit for this rule
    tokens: number
    window: 'hour' | 'day' | 'month'
  }
  fallbackStrategy?: 'next-priority' | 'lowest-cost' | 'lowest-latency' | 'fail'
}

Example Rules:

[
  {
    "id": "rule-1",
    "priority": 1,
    "pattern": { "type": "equals", "value": "gpt-4" },
    "providerId": "openai",
    "enabled": true,
    "budgetLimit": { "amount": 100, "window": "day" },
    "fallbackStrategy": "lowest-cost"
  },
  {
    "id": "rule-2",
    "priority": 2,
    "pattern": { "type": "startsWith", "value": "claude-" },
    "providerId": "anthropic",
    "enabled": true
  },
  {
    "id": "rule-3",
    "priority": 3,
    "pattern": { "type": "contains", "value": "gemini" },
    "providerId": "google",
    "enabled": true
  }
]

Routing Strategies

Available Strategies:

priority: Match rules by priority order (default)
lowest-latency: Route to fastest provider based on historical metrics
lowest-cost: Route to cheapest provider for model
least-busy: Route to provider with lowest concurrent load
tag-based: Route based on request tags
auto-router: Adaptive routing based on SLA requirements

Setting Strategy (API):

curl -X PUT http://localhost:8000/routing/strategy \
  -H "Authorization: Bearer ${AGSEC_MASTER_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"strategy": "lowest-latency"}'

Guardrails Configuration

Guardrail Settings

Via API:

curl -X PUT http://localhost:8000/guardrails \
  -H "Authorization: Bearer ${AGSEC_MASTER_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "ipAllowList": ["192.168.1.0/24"],
    "ipBlockList": ["10.0.0.5"],
    "blockedUsers": ["user-123"],
    "bannedKeywords": ["badword1", "badword2"],
    "maxRequestSize": 1000000,
    "ai_guard_enabled": false
  }'

SLM Guardrail Policies

Policy Schema:

interface GuardrailPolicy {
  id: string
  name: string
  type: 'pii_detection' | 'hate_speech' | 'prompt_injection' | 'custom_intent'
  enabled: boolean
  priority: number
  inspectionDirection: 'request' | 'response' | 'both'
  action: 'allow' | 'block' | 'sanitize'
  threshold: number         // Confidence threshold (0-1)
  detectionMethod: 'regex' | 'pattern' | 'ml' | 'slm'
  orionfence?: {
    enabled: boolean
    apiUrl: string
    apiKey: string          // Encrypted
    model: string
    threshold: number
    language: string
  }
}

Example Policies:

[
  {
    "id": "pii-policy-1",
    "name": "PII Detection",
    "type": "pii_detection",
    "enabled": true,
    "priority": 1,
    "inspectionDirection": "both",
    "action": "sanitize",
    "threshold": 0.8,
    "detectionMethod": "regex"
  },
  {
    "id": "hate-policy-1",
    "name": "Hate Speech Filter",
    "type": "hate_speech",
    "enabled": true,
    "priority": 2,
    "inspectionDirection": "both",
    "action": "block",
    "threshold": 0.7,
    "detectionMethod": "pattern"
  },
  {
    "id": "injection-policy-1",
    "name": "Prompt Injection Shield",
    "type": "prompt_injection",
    "enabled": true,
    "priority": 3,
    "inspectionDirection": "request",
    "action": "block",
    "threshold": 0.6,
    "detectionMethod": "pattern"
  }
]

Authentication Configuration

API Key Management

Create API Key (API):

curl -X POST http://localhost:8000/keys \
  -H "Authorization: Bearer ${AGSEC_MASTER_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production App Key",
    "role": "developer",
    "userId": "user-123",
    "teamId": "team-456",
    "budgetLimit": 1000,
    "requestLimit": 100000,
    "rateLimit": {
      "requestsPerMinute": 500,
      "tokensPerMinute": 500000
    },
    "expiresAt": "2025-12-31T23:59:59Z",
    "allowedModels": ["gpt-4", "gpt-3.5-turbo"],
    "mcpAccess": {
      "enabled": true,
      "allowedServers": ["time", "git"],
      "allowedTools": ["get_current_time", "git_status"]
    }
  }'

API Key Schema:

interface ApiKey {
  id: string
  key: string              // gwk_... (hashed at rest)
  name: string
  role: 'admin' | 'developer' | 'read-only'
  userId?: string
  teamId?: string
  budgetLimit?: number     // USD
  requestLimit?: number    // Total requests
  rateLimit?: {
    requestsPerMinute: number
    tokensPerMinute: number
  }
  expiresAt?: string       // ISO 8601
  allowedModels?: string[] // Model restrictions
  mcpAccess?: {
    enabled: boolean
    allowedServers?: string[]
    allowedTools?: string[]
  }
  createdAt: string
  lastUsedAt?: string
}

Session Configuration

Session Token Settings:

# Session secret for HMAC signing
SESSION_SECRET=your-secret-key-here

# Session TTL (default: 24 hours)
SESSION_TTL_MS=86400000

Rate Limiting Configuration

Global Rate Limits

Set via environment variables (applies to all API keys by default):

RATE_LIMIT_REQUESTS_PER_MINUTE=100
RATE_LIMIT_TOKENS_PER_MINUTE=100000

Per-Key Rate Limits

Override global limits for specific API keys:

curl -X PUT http://localhost:8000/keys/${KEY_ID} \
  -H "Authorization: Bearer ${AGSEC_MASTER_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "rateLimit": {
      "requestsPerMinute": 1000,
      "tokensPerMinute": 1000000
    }
  }'

Rate Limit Algorithm

Guardway Gateway uses the Token Bucket algorithm:

Bucket Capacity: requestsPerMinute or tokensPerMinute
Refill Rate: Capacity / 60 per second
Burst Handling: Can use full capacity immediately if bucket is full
Storage: Redis (shared across gateway instances)

Caching Configuration

Cache Backends

CACHE_TYPE=memory
CACHE_MAX_SIZE=10000
CACHE_TTL=3600

Cache Invalidation

Clear all caches:

curl -X POST http://localhost:8000/cache/clear \
  -H "Authorization: Bearer ${AGSEC_MASTER_KEY}"

Bypass cache per request:

curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Cache-Control: no-cache" \
  -d '...'

Observability Configuration

Prometheus Metrics

Endpoint: http://localhost:8000/metrics Enable/Disable:

PROMETHEUS_ENABLED=true
PROMETHEUS_PREFIX=gateway_

Metrics Exported:

gateway_requests_total: Total requests
gateway_requests_by_model: Requests per model
gateway_requests_by_provider: Requests per provider
gateway_tokens_total: Total tokens
gateway_cost_total: Total cost (USD)
gateway_latency_ms: Request latency
gateway_errors_total: Total errors
mcp_*: MCP-specific metrics

Jaeger Tracing

Configuration:

OTEL_ENABLED=1
OTEL_SERVICE_NAME=aigw-gateway
OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4318

Jaeger UI: http://localhost:16686

Structured Logging

Log Configuration:

LOG_LEVEL=info          # trace, debug, info, warn, error, fatal
LOG_FORMAT=json         # json, pretty
LOG_REDACT_KEYS=apiKey,authorization  # Keys to redact

Log Destinations:

stdout: Default (JSON format)
File: Set LOG_FILE=/var/log/gateway.log
Loki: Configure via log shipper (Promtail)
CloudWatch: Use AWS CloudWatch agent

MCP Configuration

MCP Server Configuration

Add MCP Server (API):

curl -X POST http://localhost:8000/mcp/servers \
  -H "Authorization: Bearer ${AGSEC_MASTER_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "custom-server",
    "mode": "remote",
    "url": "https://mcp-server.example.com",
    "allowedTools": ["tool1", "tool2"],
    "oauth": {
      "clientId": "client-id",
      "clientSecret": "client-secret",
      "tokenUrl": "https://auth.example.com/token",
      "scope": "mcp.read mcp.write"
    }
  }'

MCP Server Schema:

interface McpServerConfig {
  name: string
  mode: 'local' | 'remote'

  // For local mode (stdio)
  command?: string
  args?: string[]
  env?: Record<string, string>

  // For remote mode (HTTP)
  url?: string
  headers?: Record<string, string>

  // OAuth configuration
  oauth?: {
    clientId: string
    clientSecret: string
    tokenUrl: string
    scope?: string
  }

  // Tool filtering
  allowedTools?: string[]
  deniedTools?: string[]

  // Metadata
  tags?: string[]
  enabled: boolean
}

Webhook Configuration

Adding Webhooks

curl -X POST http://localhost:8000/webhooks \
  -H "Authorization: Bearer ${AGSEC_MASTER_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://webhook.example.com/events",
    "events": ["request.completed", "quota.threshold", "guardrail.violation"],
    "secret": "webhook-secret-key",
    "enabled": true,
    "retryConfig": {
      "maxRetries": 3,
      "backoffMs": 1000
    }
  }'

Webhook Schema:

interface Webhook {
  id: string
  url: string
  events: string[]         // Event types to subscribe to
  secret: string           // HMAC secret (encrypted at rest)
  enabled: boolean
  retryConfig?: {
    maxRetries: number
    backoffMs: number
  }
  headers?: Record<string, string>
  createdAt: string
}

Available Events:

request.completed: Request successfully processed
request.failed: Request failed
quota.threshold: Budget/request limit threshold reached
quota.exceeded: Budget/request limit exceeded
guardrail.violation: Guardrail policy violated
audit.action: Administrative action performed

Webhook Payload

{
  "event": "request.completed",
  "timestamp": "2025-01-19T12:00:00.000Z",
  "data": {
    "requestId": "req-123",
    "userId": "user-456",
    "apiKeyId": "key-789",
    "model": "gpt-4",
    "provider": "openai",
    "tokens": {
      "prompt": 100,
      "completion": 50,
      "total": 150
    },
    "cost": 0.0075,
    "latencyMs": 1234
  },
  "signature": "sha256=..."
}

Signature Verification (Node.js):

const crypto = require('crypto')

function verifySignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret)
  hmac.update(JSON.stringify(payload))
  const expected = 'sha256=' + hmac.digest('hex')
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
}

Getting Started

Guardway Gateway

Troubleshooting

Reference

​Environment Variables

​Server Configuration

​Security Configuration

​Provider API Keys

​Cloud Provider Configuration

​Redis Configuration

​PostgreSQL Configuration

​Rate Limiting Configuration

​Caching Configuration

​OpenTelemetry Configuration

​MCP Configuration

​Guardrails Configuration

​Admin UI Configuration

​Provider Configuration

​Adding a Provider (API)

​Provider Configuration Schema

​Provider-Specific Configuration

​Routing Configuration

​Routing Rules

​Routing Strategies

​Guardrails Configuration

​Guardrail Settings

​SLM Guardrail Policies

​Authentication Configuration

​API Key Management

​Session Configuration

​Rate Limiting Configuration

​Global Rate Limits

​Per-Key Rate Limits

​Rate Limit Algorithm

​Caching Configuration

​Cache Backends

​Cache Invalidation

​Observability Configuration

​Prometheus Metrics

​Jaeger Tracing

​Structured Logging

​MCP Configuration

​MCP Server Configuration

​Webhook Configuration

​Adding Webhooks

​Webhook Payload

Environment Variables

Server Configuration

Security Configuration

Provider API Keys

Cloud Provider Configuration

Redis Configuration

PostgreSQL Configuration

Rate Limiting Configuration

Caching Configuration

OpenTelemetry Configuration

MCP Configuration

Guardrails Configuration

Admin UI Configuration

Provider Configuration

Adding a Provider (API)

Provider Configuration Schema

Provider-Specific Configuration

Routing Configuration

Routing Rules

Routing Strategies

Guardrails Configuration

Guardrail Settings

SLM Guardrail Policies

Authentication Configuration

API Key Management

Session Configuration

Rate Limiting Configuration

Global Rate Limits

Per-Key Rate Limits

Rate Limit Algorithm

Caching Configuration

Cache Backends

Cache Invalidation

Observability Configuration

Prometheus Metrics

Jaeger Tracing

Structured Logging

MCP Configuration

MCP Server Configuration

Webhook Configuration

Adding Webhooks

Webhook Payload