Skip to main content

Documentation Index

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

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

​
What the gateway does

The KavachOS Gateway is a standalone HTTP reverse proxy. Every request to your API or MCP server passes through it first. The gateway:
  • Validates Bearer tokens against a KavachOS instance
  • Checks agent permissions before forwarding
  • Enforces global and per-route rate limits
  • Records an audit trail for every request
  • Handles CORS preflight
  • Strips or forwards the Authorization header depending on your config
The upstream service sees only clean, authenticated traffic. No SDK changes required on the upstream side.

​
When to use it

Use the gateway when you want to add auth to something that doesn’t have it. Common cases:
  • A local tool server or MCP server that accepts unauthenticated connections
  • A third-party API you’re exposing to agents
  • A service you can’t modify but need to wrap with auth
  • Staging environments where you want to restrict access
If you own the upstream service and can add the KavachOS SDK directly, that’s more flexible. The gateway is best when you can’t or don’t want to touch upstream code.

​
Quick start

The fastest path is the one-liner: 
npx @kavachos/gateway --upstream http://localhost:8080
This starts a gateway on port 3000 that proxies all traffic to http://localhost:8080. Requests without a valid KavachOS Bearer token are rejected with 401. Check the health endpoint to confirm it’s running: 
curl http://localhost:3000/_kavach/health
# {"status":"ok","upstream":"http://localhost:8080","timestamp":"..."}

​
Configuration

​
CLI flags

npx @kavachos/gateway \
  --upstream http://localhost:8080 \
  --port 4000 \
  --database ./kavach.db \
  --config gateway.json \
  --strip-auth \
  --no-audit
FlagDefaultDescription
--upstreamrequiredURL of the upstream service
--port3000Port the gateway listens on
--database:memory:SQLite database path for KavachOS
--config,Path to a gateway.json config file
--strip-authfalseRemove the Authorization header before forwarding
--no-auditfalseDisable audit trail recording

​
gateway.json

For more control, put your config in a JSON file and pass it with --config: 
{
  "upstream": "http://localhost:8080",
  "audit": true,
  "stripAuthHeader": false,
  "cors": {
    "origins": ["https://app.example.com"],
    "methods": ["GET", "POST", "PUT", "DELETE"],
    "credentials": true
  },
  "rateLimit": {
    "windowMs": 60000,
    "max": 100
  },
  "policies": [
    {
      "path": "/health",
      "public": true
    },
    {
      "path": "/api/read/**",
      "method": "GET",
      "requiredPermissions": [
        { "resource": "api", "actions": ["read"] }
      ]
    },
    {
      "path": "/api/**",
      "requiredPermissions": [
        { "resource": "api", "actions": ["read", "write"] }
      ],
      "rateLimit": {
        "windowMs": 60000,
        "max": 20
      }
    }
  ]
}

​
Embedded mode

Use the gateway inside your own Node.js application without starting a separate process: 
import { createKavach } from 'kavachos';
import { createGateway } from '@kavachos/gateway';

const kavach = await createKavach({
  database: { provider: 'sqlite', url: 'kavach.db' },
});

const gateway = createGateway({
  upstream: 'http://localhost:8080',
  kavach,
  audit: true,
  cors: { origins: '*' },
  rateLimit: { windowMs: 60_000, max: 100 },
  policies: [
    { path: '/_health', public: true },
    {
      path: '/api/**',
      requiredPermissions: [{ resource: 'api', actions: ['read'] }],
    },
  ],
});

// Start a standalone server
await gateway.listen(3000);

// Or use it as a handler in your existing server framework
// (pass it a Web API Request, get back a Response)
const response = await gateway.handleRequest(request);

​
Policy rules

Policies are matched in order. The first policy whose path pattern and method (if set) match the incoming request wins. 
interface GatewayPolicy {
  path: string;              // glob pattern, e.g. '/api/*', '/tools/**'
  method?: string | string[]; // 'GET', ['GET', 'POST'], etc.
  public?: boolean;          // skip auth entirely
  requireAuth?: boolean;     // default true
  requiredPermissions?: Array<{
    resource: string;
    actions: string[];
  }>;
  rateLimit?: {
    windowMs: number;
    max: number;
  };
}

​
Glob patterns

Patterns use standard glob syntax via micromatch:
PatternMatches
/api/*/api/users, /api/items (one level)
/api/**/api/users, /api/v2/users/123 (any depth)
/health/health exactly
/**everything

​
Auth flow per request

  1. Check if the path is /_kavach/health, serve locally, no upstream
  2. Handle CORS preflight if cors is configured
  3. Match the request against policies (path + method)
  4. If the matched policy is public: true or requireAuth: false, skip auth
  5. Otherwise extract the Authorization: Bearer <token> header
  6. Validate the token against KavachOS, reject with 401 if invalid
  7. Check global rate limit (keyed by agent ID or IP), reject with 429 if exceeded
  8. Check policy-level rate limit, reject with 429 if exceeded
  9. Check requiredPermissions if any, reject with 403 if insufficient
  10. Proxy the request to the upstream
  11. Record an audit entry if audit: true
  12. Return the upstream response with CORS headers merged in

​
Integration with MCP servers

The gateway works well in front of MCP tool servers. Agents that have been issued KavachOS tokens can call tools through the gateway, with permissions enforced per-route: 
{
  "upstream": "http://localhost:3001",
  "policies": [
    {
      "path": "/tools/read-file",
      "method": "POST",
      "requiredPermissions": [
        { "resource": "filesystem", "actions": ["read"] }
      ]
    },
    {
      "path": "/tools/write-file",
      "method": "POST",
      "requiredPermissions": [
        { "resource": "filesystem", "actions": ["write"] }
      ]
    },
    {
      "path": "/tools/**",
      "requiredPermissions": [
        { "resource": "mcp", "actions": ["call"] }
      ]
    }
  ]
}

​
Standalone vs embedded

Standalone (CLI)Embedded
Setupnpx @kavachos/gatewaycreateGateway(config)
ProcessSeparate processIn-process
FrameworkNone requiredWorks with any framework
Hot reloadRestart requiredYour app’s reload
Use caseQuick wrap, Docker sidecarFull control, custom middleware
In Docker, the standalone mode works as a sidecar: 
# Start your API
CMD ["node", "server.js"]

# Or start the gateway in front of it
CMD ["npx", "@kavachos/gateway", "--upstream", "http://localhost:8080", "--port", "3000", "--database", "/data/kavach.db"]

​
Configuration reference

​
upstream
string
URL of the upstream service to proxy to
​
basePath
string
default:"\"/\""
Base path prefix. Default: ”/“
​
kavach
Kavach
KavachOS instance created with createKavach()
​
policies
GatewayPolicy[]
Array of path-based access policies
​
cors
CorsConfig
CORS configuration
​
rateLimit
{ windowMs: number; max: number }
Global rate limit applied to all requests
​
audit
boolean
default:"true"
Record an audit entry for every request. Default: true
​
stripAuthHeader
boolean
default:"false"
Remove the Authorization header before forwarding to upstream. Default: false
Rate limits are tracked in memory. If you run multiple gateway instances, each tracks limits independently. For distributed rate limiting, wrap the gateway with an external store or use a single gateway instance.
Last modified on April 18, 2026