Quick Start

This guide takes you from zero to a running KalGuard sidecar with a secured agent in under five minutes.

Prerequisites

Requirement	Version
Node.js	20 or later
pnpm (or npm)	8+ (or npm 9+)
OpenSSL	any recent version (for secret generation)

1. Install

pnpm add kalguard

This installs the umbrella package which re-exports kalguard-core, kalguard-sdk, and the sidecar launcher.

tip

You can also install packages individually — see the Installation Guide.

2. Configure

Create a policy.json that defines what the agent is allowed to do:

{
  "version": "1.0",
  "rules": [
    {
      "id": "allow-dev-agent-prompts",
      "match": {
        "agentIds": ["dev-agent"],
        "actions": ["prompt:check"]
      },
      "decision": "allow",
      "reason": "Development agent may send prompts"
    },
    {
      "id": "allow-dev-agent-tools",
      "match": {
        "agentIds": ["dev-agent"],
        "actions": ["tool:execute"]
      },
      "decision": "allow",
      "reason": "Development agent may execute tools"
    }
  ],
  "defaultDecision": "deny",
  "defaultReason": "No matching policy rule"
}

warning

The example above is permissive for development. Always restrict policies before deploying to production.

3. Start the Sidecar

# Point at your policy file
export KALGUARD_POLICY_PATH=./policy.json

# Option A: Connect to KalGuard Cloud (recommended)
export KALGUARD_API_KEY=kg_live_your_key_here

# Option B: Local-only mode (generate a signing secret manually)
# export KALGUARD_TOKEN_SECRET=$(openssl rand -hex 32)

# Start the sidecar (default port 9292)
pnpm --filter kalguard-sidecar start

You should see:

[kalguard] sidecar listening on http://0.0.0.0:9292
[kalguard] policy loaded from ./policy.json (2 rules)

4. Create an Agent Token

From the Dashboard (recommended)

1. Log in at dashboard.kalguard.dev
2. Go to Access Tokens → Create Token
3. Set a name, agent ID (e.g., dev-agent), capabilities (prompt:send, tool:execute), and expiry
4. Copy the token and set it in your agent's environment:

export KALGUARD_AGENT_TOKEN="eyJhbGciOiJIUzI1NiIs..."

Local-only mode (development)

import { createAgentToken } from 'kalguard-core';

const token = createAgentToken('dev-agent', ['prompt:send', 'tool:execute'], {
  secret: process.env.KALGUARD_TOKEN_SECRET!,
  issuer: 'my-platform',
  ttlSeconds: 3600,
});

5. Integrate Your Agent

TypeScript / JavaScript

import { KalGuardClient, withPromptCheck, withToolCheck } from 'kalguard';

const kg = new KalGuardClient({
  baseUrl: 'http://localhost:9292',
  token: process.env.KALGUARD_AGENT_TOKEN!,
});

// Prompt check — sanitizes messages before the LLM call
const llmResponse = await withPromptCheck(kg, messages, async (safe) => {
  return await yourLLM.chat(safe);
});

// Tool check — validates the tool call against policy
const toolResult = await withToolCheck(kg, 'get_weather', { city: 'NYC' }, async () => {
  return await weather.get('NYC');
});

Any Language (HTTP)

import requests, os

TOKEN = os.environ["KALGUARD_AGENT_TOKEN"]

def check_prompt(messages: list) -> list:
    r = requests.post(
        "http://localhost:9292/v1/prompt/check",
        headers={"Authorization": f"Bearer {TOKEN}"},
        json={"messages": messages},
    )
    data = r.json()
    if not data["allowed"]:
        raise RuntimeError(data["message"])
    return data.get("data", {}).get("sanitizedMessages", messages)

6. Verify

Tail the audit log to confirm decisions are being recorded:

tail -f audit.log | jq .

{
  "timestamp": "2026-05-01T10:30:00.000Z",
  "requestId": "req_abc123",
  "agentId": "dev-agent",
  "action": "prompt:check",
  "decision": "allow",
  "reason": "Policy rule: allow-dev-agent-prompts"
}

Next Steps

Topic	Link
Advanced policy rules	Policy Engine
Prompt firewall tuning	Prompt Firewall
Production deployment	Deployment Guide
Full HTTP & SDK reference	API Reference

Troubleshooting

Sidecar won't start

• Verify KALGUARD_TOKEN_SECRET is set (echo $KALGUARD_TOKEN_SECRET).
• Validate policy.json with jq . policy.json.
• Check that port 9292 is free: lsof -i :9292.

Agent requests return 401 / 403

• Ensure the token has not expired.
• Confirm the agent ID in the token matches a policy rule.
• Review sidecar stderr for detailed error messages.

Policy changes are not picked up

• Set KALGUARD_POLICY_WATCH=true to enable hot-reload.
• Check file permissions — the sidecar must be able to read the policy file.