Quickstart

Get GaiterGuard running and proxy your first request in under 10 minutes

What you’ll build

By the end of this guide, you’ll have:

• GaiterGuard running in Docker with a PostgreSQL database
• A registered service (Stripe test API)
• An AI agent with a scoped Agent-Key
• A working proxy request that gets risk-assessed and forwarded

Prerequisites: Docker and Docker Compose installed on your machine.

Step 1: Clone and configure

Clone the GaiterGuard repository and set up your environment:

Clone repository

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

cp backend/.env.example backend/.env

Edit backend/.env with your configuration:

backend/.env

DATABASE_URL=postgres://pglocal:pglocal-pass@db:5432/gaiterguard
PORT=3000
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
RISK_THRESHOLD=0.5
APPROVAL_EXECUTE_TTL_HOURS=1

Security: Replace JWT_SECRET and ENCRYPTION_SECRET with long, random strings. Use openssl rand -hex 32 to generate secure values.

Step 2: Start services

Launch all containers with Docker Compose:

docker compose up --build

Wait for services to be healthy:

Service	URL	Status
Backend API	http://localhost:3000	GET /health
Frontend dashboard	http://localhost:4173	Web UI
PostgreSQL	localhost:5432	Internal

The backend automatically runs database migrations on startup. Check logs with docker compose logs backend if you see connection errors.

Step 3: Register a user

Open the dashboard at http://localhost:4173 and create your first account:

1. Sign up

   Click Sign Up and enter your email and password. This creates a user in the PostgreSQL database.

2. Log in

   Sign in with your credentials. You’ll receive a JWT access token that authenticates all dashboard API requests.

Alternatively, use the API directly:

cURL

curl -X POST http://localhost:3000/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "password": "your-secure-password"
  }'

curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "password": "your-secure-password"
  }'

Save the access_token from the login response — you’ll need it for the next steps.

Step 4: Register a service

Create a service entry for the Stripe test API. This stores the base URL, authentication type, and encrypted credentials:

cURL

curl -X POST http://localhost:3000/services \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "name": "Stripe Test API",
    "baseUrl": "https://api.stripe.com",
    "authType": "bearer",
    "credentials": {
      "bearer_token": "sk_test_your_stripe_test_key"
    }
  }'

{
  "id": 1,
  "name": "Stripe Test API",
  "baseUrl": "https://api.stripe.com",
  "authType": "bearer",
  "credential_keys": ["bearer_token"],
  "createdAt": "2026-03-03T10:00:00.000Z"
}

Credentials are encrypted with AES-256-GCM and stored in the credentials table. The bearer_token value is never returned in API responses.

Save the service id (e.g., 1) — you’ll use it when creating an agent.

Step 5: Create an agent

Provision an agent with a scoped Agent-Key:

cURL

curl -X POST http://localhost:3000/agents \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "name": "Support Bot",
    "serviceIds": [1]
  }'

{
  "agent": {
    "id": 1,
    "name": "Support Bot",
    "keyPrefix": "agt_abc12345",
    "isActive": true,
    "createdAt": "2026-03-03T10:05:00.000Z"
  },
  "apiKey": "agt_abc12345def67890ghijklmnopqrstuvwxyz",
  "services": [
    { "id": 1, "name": "Stripe Test API" }
  ]
}

Save the apiKey now! This is the only time the full key is shown. If you lose it, you’ll need to create a new agent.

Step 6: Test the proxy

Send a low-risk request through the gateway:

Low-risk GET request

curl -X POST http://localhost:3000/proxy \
  -H "Content-Type: application/json" \
  -H "Agent-Key: agt_abc12345def67890ghijklmnopqrstuvwxyz" \
  -H "Idempotency-Key: test-request-001" \
  -d '{
    "targetUrl": "https://api.stripe.com/v1/customers",
    "method": "GET",
    "headers": {},
    "body": null,
    "intent": "List all customers to display in support dashboard"
  }'

curl -X POST http://localhost:3000/proxy \
  -H "Content-Type: application/json" \
  -H "Agent-Key: agt_abc12345def67890ghijklmnopqrstuvwxyz" \
  -H "Idempotency-Key: test-request-002" \
  -d '{
    "targetUrl": "https://api.stripe.com/v1/customers/cus_test123",
    "method": "DELETE",
    "headers": {},
    "body": null,
    "intent": "Delete customer account per GDPR request"
  }'

Low-risk response (auto-forwarded)

If the risk score is below RISK_THRESHOLD (0.5), you’ll get a 200 response with the Stripe API data:

{
  "object": "list",
  "data": [...],
  "has_more": false
}

Response headers:

• X-Proxy-Status: forwarded — request was automatically approved and forwarded
• X-Idempotency-Status: processed — idempotency key was recorded

High-risk response (requires approval)

If the risk score meets or exceeds the threshold, you’ll get a 428 response:

{
  "error": "Request requires human approval",
  "action_id": "550e8400-e29b-41d4-a716-446655440000",
  "risk_score": 0.82,
  "risk_explanation": "DELETE operation with high-risk method; requires human review",
  "status_url": "/status/550e8400-e29b-41d4-a716-446655440000"
}

Step 7: Approve and execute

For blocked requests, the agent must poll for approval:

1. Poll status endpoint

   curl http://localhost:3000/status/550e8400-e29b-41d4-a716-446655440000 \
     -H "Agent-Key: agt_abc12345def67890ghijklmnopqrstuvwxyz"
   

   Response while pending:

   {
     "status": "PENDING",
     "action_id": "550e8400-e29b-41d4-a716-446655440000",
     "created_at": "2026-03-03T10:10:00.000Z"
   }
   
2. Approve in dashboard

   Open http://localhost:4173/approvals and click Approve on the pending request. You’ll see:

   • The agent’s intent: “Delete customer account per GDPR request”
   • The full HTTP request (method, URL, headers, body)
   • The risk score and explanation
3. Poll again

   Once approved, the status changes:

   {
     "status": "APPROVED",
     "action_id": "550e8400-e29b-41d4-a716-446655440000",
     "execute_url": "/proxy/execute/550e8400-e29b-41d4-a716-446655440000"
   }
   
4. Execute the request

   curl -X POST http://localhost:3000/proxy/execute/550e8400-e29b-41d4-a716-446655440000 \
     -H "Agent-Key: agt_abc12345def67890ghijklmnopqrstuvwxyz"
   

   GaiterGuard re-fetches credentials from the vault, forwards the request to Stripe, and returns:

   {
     "id": "cus_test123",
     "object": "customer",
     "deleted": true
   }
   

   Response headers:

   • X-Proxy-Status: executed-approved — request was executed after human approval

What you learned

Secret isolation

Your agent never saw the Stripe API key. GaiterGuard injected it at request time from the encrypted vault.

Risk-based gating

Low-risk GET requests passed through instantly. High-risk DELETE required human approval.

Approval workflow

Blocked requests queue for review. You approved from the dashboard, and the agent executed after polling.

Intent transparency

Every request includes a natural language intent. The LLM checks if the intent matches the actual payload.

Next steps

Installation guide

Deploy GaiterGuard to production with custom configurations.

Architecture

Learn how risk scoring, credential injection, and approval flows work.

Agent integration

Integrate GaiterGuard into your AI agent codebase with polling loops and error handling.

Agent skill

Install the bundled agent skill to teach your AI how to use the gateway protocol.