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

# 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

<Note>
  **Prerequisites**: Docker and Docker Compose installed on your machine.
</Note>

## Step 1: Clone and configure

Clone the GaiterGuard repository and set up your environment:

<CodeGroup>
  ```bash Clone repository theme={null}
  git clone https://github.com/your-username/gaiter-guard.git
  cd gaiter-guard
  ```

  ```bash Copy environment file theme={null}
  cp backend/.env.example backend/.env
  ```
</CodeGroup>

Edit `backend/.env` with your configuration:

```env backend/.env theme={null}
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
```

<Warning>
  **Security**: Replace `JWT_SECRET` and `ENCRYPTION_SECRET` with long, random strings. Use `openssl rand -hex 32` to generate secure values.
</Warning>

## Step 2: Start services

Launch all containers with Docker Compose:

```bash theme={null}
docker compose up --build
```

Wait for services to be healthy:

| Service            | URL                                            | Status        |
| ------------------ | ---------------------------------------------- | ------------- |
| Backend API        | [http://localhost:3000](http://localhost:3000) | `GET /health` |
| Frontend dashboard | [http://localhost:4173](http://localhost:4173) | Web UI        |
| PostgreSQL         | localhost:5432                                 | Internal      |

<Tip>
  The backend automatically runs database migrations on startup. Check logs with `docker compose logs backend` if you see connection errors.
</Tip>

## Step 3: Register a user

Open the dashboard at [http://localhost:4173](http://localhost:4173) and create your first account:

<Steps>
  <Step title="Sign up">
    Click **Sign Up** and enter your email and password. This creates a user in the PostgreSQL database.
  </Step>

  <Step title="Log in">
    Sign in with your credentials. You'll receive a JWT access token that authenticates all dashboard API requests.
  </Step>
</Steps>

Alternatively, use the API directly:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST http://localhost:3000/auth/register \
    -H "Content-Type: application/json" \
    -d '{
      "email": "you@example.com",
      "password": "your-secure-password"
    }'
  ```

  ```bash Login theme={null}
  curl -X POST http://localhost:3000/auth/login \
    -H "Content-Type: application/json" \
    -d '{
      "email": "you@example.com",
      "password": "your-secure-password"
    }'
  ```
</CodeGroup>

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:

<CodeGroup>
  ```bash cURL theme={null}
  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"
      }
    }'
  ```

  ```json Response theme={null}
  {
    "id": 1,
    "name": "Stripe Test API",
    "baseUrl": "https://api.stripe.com",
    "authType": "bearer",
    "credential_keys": ["bearer_token"],
    "createdAt": "2026-03-03T10:00:00.000Z"
  }
  ```
</CodeGroup>

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

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`:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST http://localhost:3000/agents \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -d '{
      "name": "Support Bot",
      "serviceIds": [1]
    }'
  ```

  ```json Response theme={null}
  {
    "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" }
    ]
  }
  ```
</CodeGroup>

<Warning>
  **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.
</Warning>

## Step 6: Test the proxy

Send a low-risk request through the gateway:

<CodeGroup>
  ```bash Low-risk GET request theme={null}
  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"
    }'
  ```

  ```bash High-risk DELETE request theme={null}
  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"
    }'
  ```
</CodeGroup>

### 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

<Steps>
  <Step title="Poll status endpoint">
    ```bash theme={null}
    curl http://localhost:3000/status/550e8400-e29b-41d4-a716-446655440000 \
      -H "Agent-Key: agt_abc12345def67890ghijklmnopqrstuvwxyz"
    ```

    Response while pending:

    ```json theme={null}
    {
      "status": "PENDING",
      "action_id": "550e8400-e29b-41d4-a716-446655440000",
      "created_at": "2026-03-03T10:10:00.000Z"
    }
    ```
  </Step>

  <Step title="Approve in dashboard">
    Open [http://localhost:4173/approvals](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
  </Step>

  <Step title="Poll again">
    Once approved, the status changes:

    ```json theme={null}
    {
      "status": "APPROVED",
      "action_id": "550e8400-e29b-41d4-a716-446655440000",
      "execute_url": "/proxy/execute/550e8400-e29b-41d4-a716-446655440000"
    }
    ```
  </Step>

  <Step title="Execute the request">
    ```bash theme={null}
    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:

    ```json theme={null}
    {
      "id": "cus_test123",
      "object": "customer",
      "deleted": true
    }
    ```

    Response headers:

    * `X-Proxy-Status: executed-approved` — request was executed after human approval
  </Step>
</Steps>

## What you learned

<CardGroup cols={2}>
  <Card title="Secret isolation" icon="lock">
    Your agent never saw the Stripe API key. GaiterGuard injected it at request time from the encrypted vault.
  </Card>

  <Card title="Risk-based gating" icon="shield-check">
    Low-risk GET requests passed through instantly. High-risk DELETE required human approval.
  </Card>

  <Card title="Approval workflow" icon="list-check">
    Blocked requests queue for review. You approved from the dashboard, and the agent executed after polling.
  </Card>

  <Card title="Intent transparency" icon="eye">
    Every request includes a natural language intent. The LLM checks if the intent matches the actual payload.
  </Card>
</CardGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Installation guide" icon="download" href="/installation">
    Deploy GaiterGuard to production with custom configurations.
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/concepts/architecture">
    Learn how risk scoring, credential injection, and approval flows work.
  </Card>

  <Card title="Agent integration" icon="puzzle-piece" href="/guides/agent-integration">
    Integrate GaiterGuard into your AI agent codebase with polling loops and error handling.
  </Card>

  <Card title="Agent skill" icon="brain" href="/guides/agent-skill">
    Install the bundled agent skill to teach your AI how to use the gateway protocol.
  </Card>
</CardGroup>