Installation

Deploy GaiterGuard with Docker or run locally for development

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

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

PORT=3000
NODE_ENV=production

JWT_SECRET=your-secret-here-use-a-long-random-string
JWT_ACCESS_EXPIRY=15m
JWT_REFRESH_EXPIRY=7d

ENCRYPTION_SECRET=minimum-32-characters-for-aes256-encryption
ENCRYPTION_SALT=gaiter-guard-salt-v1

LLM_BASE_URL=https://api.openai.com/v1
LLM_API_KEY=sk-your-openai-api-key-here
LLM_MODEL=gpt-4o-mini
LLM_TIMEOUT_MS=10000

RISK_THRESHOLD=0.5
APPROVAL_EXECUTE_TTL_HOURS=1

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:

Check status

docker compose ps

# All services
docker compose logs -f

# Backend only
docker compose logs -f backend

# Database only
docker compose logs -f db

curl http://localhost:3000/health

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:

macOS/Linux

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

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

bun --version

2. Set up PostgreSQL

Start a local PostgreSQL instance:

macOS (Homebrew)

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

sudo apt install postgresql-16
sudo systemctl start postgresql
sudo -u postgres createdb gaiterguard

docker run -d \
  --name gaiterguard-db \
  -e POSTGRES_USER=pglocal \
  -e POSTGRES_PASSWORD=pglocal-pass \
  -e POSTGRES_DB=gaiterguard \
  -p 5432:5432 \
  postgres:16-alpine

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:

From backend/ directory

bun run dev

bun run dev:backend

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

1. Use managed PostgreSQL

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

2. Deploy backend with health checks

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

3. Serve frontend via CDN

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

4. Use HTTPS everywhere

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

5. 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 exist

Fix:

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

LLM timeout errors

Error: Risk assessment failed: timeout

Fix:

1. Increase LLM_TIMEOUT_MS to 20000 (20 seconds)
2. Verify LLM_API_KEY is valid and has quota
3. Check LLM_BASE_URL is reachable from the backend container
4. 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 console

Fix:

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

Migrations fail on startup

Error: migration failed in backend logs

Fix:

1. Drop and recreate the database: dropdb gaiterguard && createdb gaiterguard
2. Run migrations manually: cd backend && bun run db:migrate
3. Check for schema conflicts if you modified schema.ts
4. 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.