Installation

Deployment options

GaiterGuard supports two installation modes:

Docker (recommended)

Production-ready deployment with PostgreSQL, backend, and frontend in containers.

Local development

Run backend and frontend with hot reload for active development and testing.

Docker installation

Prerequisites: Docker 20.10+ and Docker Compose 2.0+

1. Clone the repository

git clone https://github.com/your-username/gaiter-guard.git
cd gaiter-guard

2. Configure environment variables

Copy the example environment file:

cp backend/.env.example backend/.env

Edit backend/.env with your production values:

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

Security best practices:

Use openssl rand -hex 32 to generate JWT_SECRET and ENCRYPTION_SECRET
Set ENCRYPTION_SECRET to at least 32 characters for AES-256-GCM
Never commit .env files to version control
Rotate secrets regularly in production

3. Start all services

Launch the full stack with Docker Compose:

docker compose up --build

For detached mode (runs in background):

docker compose up --build -d

4. Verify services

Check that all containers are healthy:

docker compose ps

Service	URL	Description
Backend API	http://localhost:3000	REST API for agents and dashboard
Frontend	http://localhost:4173	React dashboard for approvals
PostgreSQL	localhost:5432	Database (not exposed in production)

The backend automatically runs database migrations on startup via bun run db:migrate. Check logs if you see “relation does not exist” errors.

5. Docker Compose reference

The docker-compose.yaml defines three services:

db (PostgreSQL)

db:
  image: postgres:16-alpine
  restart: always
  environment:
    POSTGRES_USER: pglocal
    POSTGRES_PASSWORD: pglocal-pass
    POSTGRES_DB: gaiterguard
  ports:
    - "5432:5432"
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U pglocal -d gaiterguard"]
    interval: 5s
    timeout: 5s
    retries: 5
  volumes:
    - pgdata:/var/lib/postgresql/data

The database uses a persistent volume (pgdata) to retain data across container restarts.

backend (Bun API)

backend:
  build:
    context: ./backend
    dockerfile: Dockerfile
  restart: always
  ports:
    - "3000:3000"
  environment:
    - DATABASE_URL=postgres://pglocal:pglocal-pass@db:5432/gaiterguard
    - PORT=3000
    # ... (loads from .env)
  depends_on:
    db:
      condition: service_healthy

The backend waits for PostgreSQL to be healthy before starting. Runs migrations automatically.

frontend (React + Vite)

frontend:
  build:
    context: ./frontend
    dockerfile: Dockerfile
    args:
      VITE_API_URL: http://localhost:3000
  restart: always
  ports:
    - "4173:4173"
  environment:
    - VITE_API_URL=http://localhost:3000
  depends_on:
    - backend

The frontend is served as a static build via vite preview. Update VITE_API_URL if deploying to a different domain.

Local development

Prerequisites: Bun v1.x, PostgreSQL 16+

1. Install Bun

If you don’t have Bun installed:

curl -fsSL https://bun.sh/install | bash

2. Set up PostgreSQL

Start a local PostgreSQL instance:

brew install postgresql@16
brew services start postgresql@16
creatdb gaiterguard

3. Install dependencies

This is a monorepo with backend/ and frontend/ workspaces:

# Backend dependencies
cd backend
bun install

# Frontend dependencies
cd ../frontend
bun install

4. Configure backend environment

Create backend/.env:

backend/.env

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-chars-minimum
ENCRYPTION_SALT=gaiter-guard-salt-v1
LLM_BASE_URL=https://api.openai.com/v1
LLM_API_KEY=sk-your-openai-api-key
LLM_MODEL=gpt-4o-mini
LLM_TIMEOUT_MS=10000
RISK_THRESHOLD=0.5
APPROVAL_EXECUTE_TTL_HOURS=1

Bun automatically loads .env files — no need for dotenv packages.

5. Run database migrations

Apply the Drizzle schema to PostgreSQL:

cd backend
bun run db:migrate

This runs drizzle-kit push to sync your schema with the database. You’ll see output like:

Applying migrations...
✓ Created table "users"
✓ Created table "services"
✓ Created table "credentials"
✓ Created table "agents"
✓ Created table "approval_queue"

If you modify backend/src/db/schema.ts, run bun run db:generate to generate migrations, then bun run db:migrate to apply them.

6. Start the backend

Run the backend server with hot reload:

bun run dev

The server starts at http://localhost:3000 with hot module replacement. Changes to src/ files auto-reload. Available backend scripts (from backend/package.json):

{
  "scripts": {
    "dev": "bun --watch src/server.ts",
    "start": "bun run db:migrate && bun src/server.ts",
    "db:generate": "bun drizzle-kit generate",
    "db:migrate": "bun drizzle-kit push"
  }
}

7. Start the frontend

In a separate terminal:

cd frontend
bun run dev

The Vite dev server starts at http://localhost:5173 with HMR (hot module replacement). Available frontend scripts (from frontend/package.json):

{
  "scripts": {
    "dev": "vite dev",
    "build": "vite build",
    "start": "vite preview --host"
  }
}

8. Verify local setup

Test the backend health endpoint:

curl http://localhost:3000/health

Expected response:

{ "status": "ok" }

Open the frontend at http://localhost:5173 and create a test account.

Environment variables reference

Database

Variable	Description	Example
`DATABASE_URL`	PostgreSQL connection string	`postgres://user:pass@host:5432/db`

Server

Variable	Description	Default
`PORT`	HTTP server port	`3000`
`NODE_ENV`	Environment mode	`development`

JWT Authentication

Variable	Description	Default
`JWT_SECRET`	Secret for signing JWTs	(required)
`JWT_ACCESS_EXPIRY`	Access token TTL	`15m`
`JWT_REFRESH_EXPIRY`	Refresh token TTL	`7d`

Encryption

Variable	Description	Notes
`ENCRYPTION_SECRET`	AES-256-GCM encryption key	Min 32 chars
`ENCRYPTION_SALT`	Salt for key derivation	Change per deployment

LLM Risk Assessment

Variable	Description	Example
`LLM_BASE_URL`	OpenAI-compatible API base URL	`https://api.openai.com/v1`
`LLM_API_KEY`	API key for LLM provider	`sk-...`
`LLM_MODEL`	Model identifier	`gpt-4o-mini`
`LLM_TIMEOUT_MS`	Request timeout in milliseconds	`10000`

You can use any OpenAI-compatible API (OpenAI, Azure OpenAI, Together AI, Ollama with openai-compat mode). Just change LLM_BASE_URL and LLM_API_KEY.

Risk & Approval

Variable	Description	Range
`RISK_THRESHOLD`	Score at or above this triggers approval	`0.0`–`1.0` (default `0.5`)
`APPROVAL_EXECUTE_TTL_HOURS`	Hours until approved requests expire	Default `1`

Production deployment

Recommended architecture

Use managed PostgreSQL

Instead of the db container, use a managed PostgreSQL service (AWS RDS, Google Cloud SQL, Supabase) with automated backups and replication.

Deploy backend with health checks

Deploy the backend container to Kubernetes, ECS, or Fly.io. Configure health checks on GET /health.

Serve frontend via CDN

Build the frontend (bun run build) and serve static files via Cloudflare, Vercel, or S3 + CloudFront.

Use HTTPS everywhere

Terminate TLS at a load balancer (ALB, Cloudflare). Never expose unencrypted API endpoints.

Set up secret management

Store JWT_SECRET, ENCRYPTION_SECRET, and LLM_API_KEY in AWS Secrets Manager, HashiCorp Vault, or your platform’s secret store.

Security checklist

Secrets rotation

Rotate JWT_SECRET monthly (invalidates all sessions)
Rotate ENCRYPTION_SECRET with data re-encryption migration
Use short-lived LLM_API_KEY with scoped permissions

Network isolation

Run backend and database in a private VPC
Expose only the backend API via load balancer
Block direct database access from the internet

Monitoring

Log all approval actions (who approved what, when)
Alert on failed LLM risk assessments (fallback to method heuristics)
Monitor RISK_THRESHOLD hit rate (tune if too many/few approvals)

Access control

Limit dashboard access to authorized personnel
Use SSO/SAML for user authentication in production
Audit who creates and revokes agent keys

Troubleshooting

Database connection errors

Error: ECONNREFUSED or relation does not existFix:

Verify PostgreSQL is running: docker compose ps or pg_isready
Check DATABASE_URL matches your PostgreSQL credentials
Run migrations: bun run db:migrate
Check logs: docker compose logs db

LLM timeout errors

Error: Risk assessment failed: timeoutFix:

Increase LLM_TIMEOUT_MS to 20000 (20 seconds)
Verify LLM_API_KEY is valid and has quota
Check LLM_BASE_URL is reachable from the backend container
Monitor LLM provider status page

When the LLM fails, GaiterGuard falls back to method-based heuristics (+0.3 risk boost), so DELETE/PUT requests are blocked until the LLM recovers.

Frontend can't reach backend

Error: Network error in browser consoleFix:

Verify backend is running: curl http://localhost:3000/health
Check VITE_API_URL in frontend .env or docker-compose.yaml
Ensure CORS is configured (backend allows http://localhost:5173 in dev)
For production, update VITE_API_URL to your backend domain

Migrations fail on startup

Error: migration failed in backend logsFix:

Drop and recreate the database: dropdb gaiterguard && createdb gaiterguard
Run migrations manually: cd backend && bun run db:migrate
Check for schema conflicts if you modified schema.ts
Generate fresh migrations: bun run db:generate

Next steps

Quickstart

Test your installation with a complete proxy workflow.

Configuration

Tune risk thresholds, approval TTLs, and LLM provider settings.

Agent integration

Integrate GaiterGuard into your AI agent codebase.

Architecture

Understand how GaiterGuard works under the hood.

Get Started

Core Concepts

Guides

Deployment options

Docker (recommended)

Local development

Docker installation

1. Clone the repository

2. Configure environment variables

3. Start all services

4. Verify services

5. Docker Compose reference

Local development

1. Install Bun

2. Set up PostgreSQL

3. Install dependencies

4. Configure backend environment

5. Run database migrations

6. Start the backend

7. Start the frontend

8. Verify local setup

Environment variables reference

Database

Server

JWT Authentication

Encryption

LLM Risk Assessment

Risk & Approval

Production deployment

Recommended architecture

Security checklist

Troubleshooting

Next steps

Quickstart

Configuration

Agent integration

Architecture

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Documentation Index

​Deployment options

Docker (recommended)

Local development

​Docker installation

​1. Clone the repository

​2. Configure environment variables

​3. Start all services

​4. Verify services

​5. Docker Compose reference

​Local development

​1. Install Bun

​2. Set up PostgreSQL

​3. Install dependencies

​4. Configure backend environment

​5. Run database migrations

​6. Start the backend

​7. Start the frontend

​8. Verify local setup

​Environment variables reference

​Database

​Server

​JWT Authentication

​Encryption

​LLM Risk Assessment

​Risk & Approval

​Production deployment

​Recommended architecture

​Security checklist

​Troubleshooting

​Next steps

Quickstart

Configuration

Agent integration

Architecture

Build docs developers (and LLMs) love

Deployment options

Docker installation

1. Clone the repository

2. Configure environment variables

3. Start all services

4. Verify services

5. Docker Compose reference

Local development

1. Install Bun

2. Set up PostgreSQL

3. Install dependencies

4. Configure backend environment

5. Run database migrations

6. Start the backend

7. Start the frontend

8. Verify local setup

Environment variables reference

Database

Server

JWT Authentication

Encryption

LLM Risk Assessment

Risk & Approval

Production deployment

Recommended architecture

Security checklist

Troubleshooting

Next steps