Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.igrisecurity.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Architecture

Igris is a monorepo with two primary services, a shared database, and a Redis cache layer.

​
System Overview

​
Components

​
API Server (Hono)

The backend runs on Hono and listens on port 3100. It handles:
  • Gateway routes (/v1/mcp/:slug) — intercept MCP tool calls, evaluate policies, forward to upstream
  • REST API (/api/v1/*) — CRUD for policies, servers, sessions, audit events, billing
  • Auth (/api/auth/*) — Better Auth endpoints for session management
  • SSE (/api/v1/events) — real-time event stream for dashboard updates

​
Web Frontend (Next.js)

The dashboard runs on Next.js on port 3200 and provides:
  • Governance management (servers, policies, sessions)
  • Real-time observe dashboard with risk heat maps
  • Organization settings, member management, billing

​
Database (Neon PostgreSQL)

All persistent state lives in Neon PostgreSQL. The schema is managed by Drizzle ORM with auto-migrations on startup. Key tables:
TablePurpose
user, account, sessionBetter Auth identity
organization, memberMulti-tenancy
connectionsConnection configs (HTTP MCP / LLM gateway, encrypted credentials)
mcp_policiesGovernance rules per connection
agent_sessionsActive gateway sessions
audit_eventsGateway audit trail

​
Cache (Upstash Redis)

Upstash Redis handles:
  • Policy cache — hot policies cached with TTL to avoid DB lookups on every tool call
  • Rate limiting — sliding window counters for rate-limit policy rules
  • SSE pub/sub — event fan-out to connected dashboard clients
  • Session state — fast lookup for kill-switch status

​
Authentication (Better Auth)

Better Auth provides:
  • Email/password and OAuth (GitHub, Google) login
  • Organization-scoped sessions with RBAC
  • API key generation for programmatic access (proxy)
  • Session tokens stored as igris.session_token cookies

​
Proxy Flow

When an MCP client calls a tool through the Igris proxy:
  1. Request arrives at /v1/mcp/:slug with the tool name and arguments
  2. Auth check — validate API key or session cookie
  3. Org resolution — determine which organization owns this connection
  4. Policy evaluation — load rules from cache (or DB on cache miss), evaluate first-match against the tool name with conditions
  5. Action execution:
    • allow → forward to upstream, log the event
    • deny → return error to client, log the denial
    • alert → forward to upstream, log + emit anomaly event via SSE
  6. Anomaly check — evaluate rate spike and destructive pattern detectors
  7. Audit write — persist the event to audit_events with timing, result, and metadata
  8. SSE broadcast — push real-time event to connected dashboard clients

​
Deployment

Igris deploys to EC2 via GitHub Actions with a systemd service:
  • API server runs as a systemd unit on EC2 (Ubuntu)
  • Next.js frontend deployed to Vercel (or a separate EC2 instance)
  • Neon for managed PostgreSQL (serverless, auto-scaling)
  • Upstash for managed Redis (serverless, per-request pricing)
  • Migrations applied automatically via drizzle-kit migrate on deploy
See Self-Hosted → Docker for deployment instructions.