Zehrava Gate Docs

Zehrava Gate is the write-path control plane for AI agents. Agents can read systems freely, but any real-world action — sending email, importing CRM records, updating databases, issuing refunds, publishing files — must pass through Gate first. Agents submit an intent, Gate evaluates policy, optionally requests human approval, then issues a signed execution order. Every step is deterministic, auditable, and fail-closed.

Quickstart

Start the Gate server with npx — no install required for the server itself:

npx zehrava-gate --port 4000

Or install globally:

npm install -g zehrava-gate
zehrava-gate --port 4000

Server options:

Register an agent

Before an agent can submit intents, it needs to be registered. Registration returns an API key — store this securely. It cannot be retrieved again.

curl -X POST http://localhost:4000/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{"name": "my-crm-agent", "riskTier": "standard"}'

{
  "agentId": "agt_a1b2c3d4e5f6",
  "apiKey":  "gate_sk_••••••••••••••••••••",
  "name":    "my-crm-agent",
  "riskTier": "standard"
}

The riskTier field is stored for auditing. Current values: standard, elevated, restricted. Future policy enforcement will gate actions by tier.

Your first intent

Create a policy file first. Drop it in your --policy-dir:

# policies/support-reply.yaml
id: support-reply
destinations: [zendesk.reply, intercom.reply]
auto_approve_under: 1
block_if_terms:
  - "refund guaranteed"
  - "legal action"
expiry_minutes: 30

Then submit an intent from your agent:

const { Gate } = require('zehrava-gate')
const gate = new Gate({ endpoint: 'http://localhost:4000', apiKey: 'gate_sk_...' })

const p = await gate.propose({
  payload:     'Thank you — your issue has been resolved.',
  destination: 'zendesk.reply',
  policy:      'support-reply',
  recordCount: 1
})

console.log(p.status) // "approved" | "blocked" | "pending_approval" | "duplicate_blocked"
console.log(p.intentId)
console.log(p.blockReason) // set if status === "blocked" or "duplicate_blocked"

Gate evaluates the policy immediately and returns one of four statuses:

• approved — passed all rules, within auto-approve threshold. Safe to request execution.
• blocked — violated a policy rule. Do not proceed. Check blockReason.
• pending_approval — within policy but requires human review. Poll /v1/intents/:id for status updates, or register a webhook.
• duplicate_blocked — idempotency_key matched an existing intent. The action was already submitted and Gate will not re-evaluate it.

Policy overview

Policies are YAML files stored in your --policy-dir. Gate loads them on startup and caches them. Each policy has an id that your agent references when submitting an intent via gate.propose().

Rules are evaluated top-to-bottom; the first rule that produces a decision ends evaluation:

All policy fields

Policy examples

Support reply — auto-approve safe messages, block sensitive terms

id: support-reply
destinations: [zendesk.reply, intercom.reply, freshdesk.reply]
allowed_types: [text, json]
block_if_terms:
  - "refund guaranteed"
  - "legal action"
  - "sue"
auto_approve_under: 1   # single reply → auto-approve
expiry_minutes: 30

CRM import — auto-approve small batches, review large ones

id: crm-low-risk
destinations: [salesforce.import, hubspot.contacts]
allowed_types: [csv, json]
auto_approve_under: 100        # ≤100 records → auto
require_approval_over: 100     # >100 records → human review
expiry_minutes: 60

Finance — always require human approval

id: finance-high-risk
destinations: [stripe.refund, quickbooks.journal, netsuite.payment]
require_approval: always
expiry_minutes: 15              # short window — stale approvals are dangerous

Schema-aware policy — validate fields, rate limit, env overrides

id: schema-checked-email
destinations: [sendgrid.send, loops.send]

field_checks:
  - path: "to"
    required: true
    pattern: "^[^@]+@[^@]+\\.[^@]+$"
  - path: "amount"
    min: 1
    max: 100

rate_limits:
  per_agent_per_hour: 50
  per_agent_per_day: 200

environments:
  production:
    require_approval: always
  development:
    require_approval: never

auto_approve_under: 1

Internal blog publish — scoped destination, always approve

id: blog-publish
destinations: [blog.publish, cms.publish]
require_approval: always
expiry_minutes: 120

API — Register agent

{
  "agentId":  "agt_a1b2c3d4",
  "apiKey":   "gate_sk_••••••••••••",
  "name":     "my-crm-agent",
  "status":   "active"
}

API — Agent registry

API — Submit intent

{
  "intentId":       "int_a1b2c3d4e5f6",
  "status":         "approved",          // approved | blocked | pending_approval | duplicate_blocked
  "risk_score":     0.42,                // 0–1 composite risk signal
  "risk_level":     "medium",            // low | medium | high | critical
  "reason_code":    "approved_by_policy",
  "blockReason":    null,
  "expiresAt":      "2026-03-08T12:00:00.000Z"
}

API — List intents

API — Approve

{ "status": "approved", "approvedAt": "2026-03-08T12:00:00.000Z" }

API — Reject

API — Execute

{
  "executionId":    "exe_a1b2c3d4",
  "execution_token": "gex_••••••••••••",  // one-time, 15min TTL
  "intent_id":      "int_a1b2c3d4e5f6",
  "expires_at":     "2026-03-08T12:15:00.000Z",
  "mode":           "runner_exec"
}

API — Execution status

{
  "executionId":  "exe_a1b2c3d4",
  "intent_id":   "int_a1b2c3d4e5f6",
  "mode":         "runner_exec",
  "status":       "succeeded",          // pending | executing | succeeded | failed | expired
  "worker_report": { "note": "Imported 847 records" },
  "created_at":   "2026-03-08T12:00:00.000Z",
  "completed_at": "2026-03-08T12:00:04.000Z"
}

API — Report outcome

// Worker reports success
{
  "status":  "succeeded",
  "report":  { "records_written": 847, "duration_ms": 1240 }
}

API — Policy decision

{
  "intent_id":   "int_a1b2c3d4e5f6",
  "decision":     "approved",
  "reason_code":  "approved_by_policy",
  "risk_score":   0.42,
  "risk_level":   "medium",
  "evaluated_at": "2026-03-08T12:00:00.000Z"
}

API — Audit trail

[
  { "eventType": "proposed",            "actor": "my-crm-agent", "createdAt": "..." },
  { "eventType": "policy_checked",      "actor": "system",       "metadata": { "result": "approved", "risk_score": 0.42 } },
  { "eventType": "approved",            "actor": "system",       "createdAt": "..." },
  { "eventType": "execution_requested", "actor": "my-crm-agent", "createdAt": "..." },
  { "eventType": "execution_succeeded", "actor": "worker",       "createdAt": "..." }
]

API — Metrics

{
  "actions_attempted":    142,
  "actions_blocked":      18,
  "actions_pending":      3,
  "actions_approved":     121,
  "actions_succeeded":    115,
  "actions_failed":       6,
  "actions_duplicate":    4,
  "avg_approval_latency_ms": 4320
}

SDK — Install

npm install zehrava-gate

// CommonJS
const { Gate } = require('zehrava-gate')

// ESM
import { Gate } from 'zehrava-gate'

const gate = new Gate({
  endpoint: 'http://localhost:4000',  // your Gate server URL
  apiKey:   'gate_sk_•••••••••••••'    // from /v1/agents/register
})

SDK — Methods

gate.propose(opts)

Submits intent to POST /v1/intents. All V2 fields supported. The /v1/propose alias still works for backward compat.

const p = await gate.propose({
  payload:      './leads.csv',
  destination:  'salesforce.import',
  policy:       'crm-low-risk',
  recordCount:  847,
  on_behalf_of: 'agt_orchestrator_id',  // optional
  expiresIn:    '2h'                      // optional
})
// p.intentId, p.status, p.risk_score, p.risk_level, p.blockReason, p.expiresAt

gate.approve({ intentId })

Calls POST /v1/intents/:id/approve.

await gate.approve({ intentId: p.intentId })

gate.reject({ intentId, reason })

Calls POST /v1/intents/:id/reject.

await gate.reject({ intentId: p.intentId, reason: 'Flagged for review' })

gate.execute({ intentId })

Calls POST /v1/intents/:id/execute. Returns a signed execution order with a 15-minute token.

const order = await gate.execute({ intentId: p.intentId })
// order.executionId, order.execution_token, order.expires_at

gate.verify({ intentId })

Fetch full intent details including decision record and audit trail.

const detail = await gate.verify({ intentId: p.intentId })
// detail.intentId, detail.status, detail.risk_score, detail.decision ...

Python SDK

Install the Python SDK — zero dependencies, works with Python 3.8+. Supports LangGraph, CrewAI, AutoGen, and any custom agent.

pip install zehrava-gate

from zehrava_gate import Gate, GateError

gate = Gate(
    endpoint="http://localhost:4000",
    api_key="gate_sk_..."
)

p = gate.propose(
    payload="Thank you — your issue is resolved.",
    destination="zendesk.reply",
    policy="support-reply",
    record_count=1
)

# p["status"] → "approved" | "blocked" | "pending_approval" | "duplicate_blocked"
if p["status"] in ["blocked", "duplicate_blocked"]:
    raise GateError(p["blockReason"])

LangGraph integration

from langgraph.graph import StateGraph
from zehrava_gate import Gate, GateError

gate = Gate(endpoint="http://localhost:4000", api_key="gate_sk_...")

def send_crm_import(state):
    p = gate.propose(
        payload=state["csv_path"],
        destination="salesforce.import",
        policy="crm-low-risk",
        record_count=state["record_count"],
        on_behalf_of=state.get("orchestrator_id")
    )
    if p["status"] in ["blocked", "duplicate_blocked"]:
        return {**state, "error": p["blockReason"]}
    if p["status"] == "pending_approval":
        return {**state, "intent_id": p["intentId"], "waiting": True}
    return {**state, "sent": True}

Webhooks

Instead of polling, register a webhook URL. Gate fires once — on approved or rejected. Execution outcome events are on the roadmap.

// JavaScript
const p = await gate.propose({ ... })

await gate.registerWebhook({
  intentId: p.intentId,
  url: 'https://your-app.com/gate-callback',
  secret: 'your-secret'           // sent as X-Gate-Secret header
})

# Python
gate.register_webhook(
    intent_id=p["intentId"],
    url="https://your-app.com/gate-callback",
    secret="your-secret"
)

The webhook payload:

{
  "intentId":   "int_a1b2c3d4",
  "event":      "approved",        // approved | rejected
  "actor":      "system",           // system or reviewer that approved/rejected
  "firedAt":    "2026-03-08T11:30:00.000Z"
}

Proxy (V3)

Gate can govern agents without SDK changes by running as a forward proxy. The proxy submits each outbound request as an intent. Gate forwards only approved requests.

HTTP forward proxy (Phase 1)

Route outbound HTTP traffic through Gate:

export HTTP_PROXY=http://localhost:4001
export HTTPS_PROXY=http://localhost:4001

If a destination is unknown or blocked, the proxy returns 403. This is intentional fail-closed behavior.

HTTPS interception (MITM) (Phase 2)

Enable TLS interception to govern HTTPS requests at the payload level:

export GATE_TLS_INTERCEPT=true
# restart Gate

Trust Gate’s CA certificate in your agent runtime:

# Download CA
curl -o gate-ca.crt http://localhost:3001/v1/proxy/ca.crt

# Node
export NODE_EXTRA_CA_CERTS=/path/to/gate-ca.crt

# curl
curl --cacert /path/to/gate-ca.crt https://api.example.com

Pending approvals: retry or hold

When Gate returns pending_approval, the proxy supports two patterns:

• Retry (default): proxy returns 202 with X-Gate-Intent-Id and Retry-After. Re-send the same request with X-Gate-Intent-Id.
• Hold + auto-replay (opt-in): set X-Gate-Wait: true. Gate holds the connection open and forwards automatically when approved. Timeout uses GATE_HOLD_TIMEOUT_MS (default 15 minutes).

Inspect held connections

GET /v1/proxy/held  # auth required

Destination naming gotcha

The proxy can emit host-based destinations like api.stripe.com.http. If your policy allowlist expects logical names like stripe.refund, add an override in config/destinations.yaml so host+path maps to your logical destination. Otherwise Gate will block due to allowlist mismatch.

LangChain + LangGraph

Gate integrates cleanly with LangChain tools. The pattern is simple: submit an intent before tool execution. Run the tool only if Gate approves.

Wrap tools (GateTool)

The repo contains packages/langchain-gate, which provides GateTool and GateToolkit. It wraps any Tool with a Gate checkpoint:

const { Gate } = require('zehrava-gate')
const { GateTool, GateBlockedError } = require('@zehrava/langchain-gate')

const gate = new Gate({ endpoint: 'http://localhost:3001', apiKey: 'gate_sk_...' })

const governed = new GateTool({ tool: emailTool, gate, policy: 'outbound-email', destination: 'sendgrid.send' })

try {
  await governed._call(JSON.stringify({ to: 'user@co.com', subject: '...' }))
} catch (err) {
  if (err instanceof GateBlockedError) console.error(err.blockReason)
}

Branch graphs (gateNode + gateRouteAfter)

LangGraph graphs can branch on Gate’s decision. Use gateNode() to submit intent and write gateStatus into state. Use gateRouteAfter() to route edges.

Works With

Zehrava Gate is designed to complement existing agent governance and security tooling. It focuses on one thing: human approval gates for high-consequence writes. Other tools handle autonomous policy enforcement, output validation, and observability. Together, they create a complete governance stack.

Microsoft Agent Governance Toolkit

Microsoft's Agent Governance Toolkit provides deterministic policy enforcement (<0.1ms), zero-trust agent identity, execution sandboxing, and SRE tooling. It handles autonomous governance at scale — 95% of agent actions auto-governed via policy.

Zehrava Gate sits on top as the human-in-the-loop approval layer for the 5% of actions that always need human eyes: email blasts, database deletes, financial transactions, customer-facing content.

Integration pattern:

from agent_os import PolicyEngine
from zehrava import Gate

# Microsoft's policy engine handles auto-allow/deny
policy = PolicyEngine(capabilities=...)
decision = policy.evaluate(agent_id, action, tool)

if decision.allowed:
    # Auto-allowed by policy — proceed
    execute_action()
elif decision.require_human_approval:
    # Route to Zehrava for visual approval
    intent = gate.propose(action, payload)
    if intent.status == "approved":
        execute_action()

Microsoft's toolkit includes an EscalationHandler for human approval, but it's backend-only (webhook or in-memory queue). Zehrava provides the approval dashboard, persistent history, and async intent lifecycle that teams need in production.

Read the full comparison →

Other Tools

NeMo Guardrails (NVIDIA) and Guardrails AI validate LLM outputs. Gate validates agent actions. Use both: Guardrails ensures the model's words are safe, Gate ensures the agent's actions are approved.

LiteLLM and Portkey provide LLM gateway routing, caching, and observability. Gate works transparently behind them — it sees tool calls, not model calls.

Dashboard

The dashboard at /dashboard on your Gate server shows every pending intent. No code required to review and approve — it's the interface for humans in the loop.

For each intent you can see:

• Agent name, destination, policy, record count
• Time remaining before expiry
• Payload hint (type + size — not full content by default)
• Full audit trail of events so far

Try it at zehrava.com/dashboard →

Audit trail

Every intent generates an immutable sequence of audit events, written server-side. Agents have no API route to write or modify audit events.

Event types in order:

• proposed — agent submitted the intent
• policy_checked — Gate evaluated YAML policy + risk score
• approved — auto-approved by policy, or human approved in dashboard
• rejected — human rejected (includes reason)
• blocked — policy blocked it (includes reason_code). Terminal.
• expired — approval window elapsed. Terminal.
• duplicate_blocked — idempotency_key matched. Terminal.
• execution_requested — execution order issued (gex_ token, 15min TTL)
• execution_succeeded — worker reported success
• execution_failed — worker reported failure

Intent lifecycle

POST /v1/intents
  ↓
intent → policy_checked
  ├── blocked              → terminal
  ├── duplicate_blocked    → terminal (idempotency key matched)
  ├── approved             → auto-approved by policy or human approval; eligible for execution
  └── pending_approval     → human review required
        ├── approved        → ready for execution
        ├── rejected        → terminal
        └── expired         → terminal

approved
  ↓
execution_requested (POST /v1/intents/:id/execute)
  ↓
worker executes in your VPC (runner_exec)
  ↓
POST /v1/executions/:id/report
  ├── execution_succeeded  → terminal
  └── execution_failed     → terminal

Fail closed

If Gate is unreachable, your agent must halt and never perform the write outside Gate.

Gate is middleware. If the HTTP call to /v1/intents (or gate.propose()) fails with a network error, the safe behavior is to treat it as a block and not execute the write. Proceeding silently bypasses Gate entirely.

try {
  const p = await gate.propose({ ... })
  if (p.status === 'blocked' || p.status === 'duplicate_blocked')
    throw new Error(p.blockReason || 'Duplicate intent blocked')
  if (p.status === 'pending_approval') return // wait — do not proceed
  // status === 'approved' → safe to request execution
} catch (err) {
  // Gate unreachable or returned error — fail closed
  console.error('Gate check failed — halting write', err.message)
  throw err // do NOT proceed
}

Multi-agent pipelines

In pipelines where one agent orchestrates others, use on_behalf_of to record the full chain of accountability in the audit trail:

// Leaf agent submitting an intent on behalf of the orchestrator
await gate.propose({
  payload:      data,
  destination:  'salesforce.import',
  policy:       'crm-low-risk',
  on_behalf_of: 'agt_orchestrator_abc123'
})

The audit trail will record both the calling agent and the orchestrating agent. Without on_behalf_of, only the leaf agent appears — making the orchestrator's role invisible in the audit.

Comparisons

Gate occupies a specific layer in the agent infrastructure stack. Two comparison pages explain how Gate fits with other tools teams use in the same category.

• Zehrava Gate vs Tetrate — Tetrate is an Envoy-based AI gateway platform. Gate is a write-path checkpoint. Full breakdown of both platforms.
• Zehrava Gate vs Tetrate Agent Router Service — Exact comparison of the Agent Router product specifically. How enforcement point and approval model differ.

Roadmap

Gate today is cooperative — agents call the SDK voluntarily. The roadmap closes that gap. Here is what is being built, in priority order.

1. Network-level enforcement — Gate V3 (top priority)

The current model requires agents to call Gate. A cooperative agent that skips the SDK call bypasses governance entirely. Gate V3 closes this with a forward proxy and credential vault integration.

Three deployment modes in V3:

• Forward proxy — set HTTP_PROXY=http://gate.internal:4001. All outbound HTTP routes through Gate. No code change in the agent. Gate intercepts, evaluates policy, holds or passes.
• Reverse proxy — Gate deployed in front of specific APIs. Agent routes to Gate's URL instead of the destination directly.
• Credential vault (gate_exec) — Gate holds no credentials. Fetches ephemerally from 1Password, HashiCorp Vault, or AWS Secrets Manager at execution time. Agent submits payload only — never touches production credentials. Two audit logs: Gate + credential provider.

The 1Password integration uses Service Account JWTs scoped to a single vault. Gate fetches credentials at execution time, uses them, then discards them from memory. The agent process never holds a production credential. See the full V3 spec at /v3/.

Until enforcement ships, Gate is most effective for teams that control the agent code and commit to the SDK integration pattern.

2. Schema-aware policies

Current policy evaluation is structural — record count, destination, substring terms. Schema-aware policies evaluate the content of the write against a defined schema. Examples:

• Block CRM imports where email field is empty on more than 20% of records
• Flag financial writes where amount exceeds a threshold per transaction
• Require approval for database mutations where DELETE affects more than N rows

3. Environment-aware evaluation

Policies will support environment flags. A write that auto-approves in staging requires human approval in production. Environment is passed at intent submission and changes which policy thresholds apply.

4. Cryptographically signed audit log

Current audit events are append-only in SQLite. A database admin can edit them. The signed audit log adds an HMAC signature to every event at write time. Tampering becomes detectable. This is the gap between Gate's current audit trail and compliance-grade immutability.

5. External log drain

Export audit events to S3, Splunk, or any SIEM via webhook stream. Required for teams that need audit log retention outside the Gate database.