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.

​
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: 
git clone https://github.com/your-username/gaiter-guard.git
cd gaiter-guard
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:
ServiceURLStatus
Backend APIhttp://localhost:3000GET /health
Frontend dashboardhttp://localhost:4173Web UI
PostgreSQLlocalhost:5432Internal
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 -X POST http://localhost:3000/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "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 -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"
    }
  }'
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 -X POST http://localhost:3000/agents \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "name": "Support Bot",
    "serviceIds": [1]
  }'
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: 
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"
  }'

​
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us