Vek Series

VekInbox

Open Source

Durable human approval queue for AI agents. Agents submit requests, humans review in a web inbox, and agents resume via signed webhooks.

Quick start

Start with the primary command, then continue with the full workflow below.

git clone https://github.com/LatticeAG/VekInbox.git

Problem

Production agent loops inevitably reach decision points that no operator is comfortable leaving to an autonomous model - approving a high-value payment, confirming a destructive database operation, validating a legal document before sending, or authorizing a production deployment. The standard solution is a one-off webhook, a polling loop that checks a shared spreadsheet, or a custom approve-widget hardcoded into the agent's tool definitions. Every one of these is brittle: the agent restarts and loses the pending state, the webhook URL changes and the approval never arrives, the timeout is hardcoded and no escalation happens when the human is away. There is no durable, framework-agnostic approval queue that persists across agent restarts, supports timeout escalation, routes to the right reviewer automatically, and fires signed webhooks back to the agent with at-least-once delivery semantics.

Solution

VekInbox is a durable approval queue where AI agents submit requests for human review and resume via signed webhooks or SDK polling. Requests persist in Postgres, survive agent restarts, and include automatic timeout and escalation policies. The primary integration surface is the SDK (@latticeag/vekinbox for TypeScript, vekinbox for Python) - agents create requests programmatically, wait for resolution, and resume via HMAC-SHA256-signed webhooks with retry and backoff. The architectural choice is agent SDK-first with a declarative policy language: each request type defines delay, escalation, and notification rules in the same policy language regardless of request shape, and key-based idempotency prevents duplicate requests for the same action. Multi-tenant workspaces isolate agents, requests, and channel configurations. Self-hostable via Docker Compose (~5 min) or use the managed SaaS.

How it works

Start the stack: git clone https://github.com/LatticeAG/VekInbox.git && cd VekInbox && cp .env.example .env && docker compose up --build; the API is ready when http://localhost:3001/health returns {"status":"ok"}.

On first start (EMPTY_DB=true), the entrypoint seeds demo data and prints an API key to the logs: docker compose logs api | grep "API Key" - save it, it is shown only once.

From your agent, create a request via the SDK: const inbox = new VekInbox({ apiKey, baseUrl: "http://localhost:3001/v1" }); await inbox.requests.create({ workspaceId, agentId, key: "invoice.pay.001", title: "Approve $450 invoice payment?", resumeWebhook: "https://my-agent.example.com/resume" }) - the key field provides idempotency.

The request persists in Postgres with a stable UUID and status pending; duplicate submissions with the same key return the existing request instead of creating a duplicate.

The human reviews the request in the web inbox (or via CLI/email, with Slack coming), approving, rejecting, or cancelling with optional notes; the verdict is recorded with the reviewer's identity and timestamp for audit trails.

On resolution, VekInbox fires an HMAC-SHA256-signed webhook to the agent's resumeWebhook with the verdict, retrying with backoff until acknowledged; alternatively the agent polls with inbox.requests.waitForResolution(request.id, { timeout: "1h" }).

If the deadline passes without human resolution, the timeout and escalation policy fires - notify the backup reviewer, auto-deny, or apply a configured default verdict, with every stage logged.

Technical architecture

Each handoff carries structured context through the product's execution path. Hover a node to inspect its role.

Agent SDK

Step 1: Agent SDK receives structured context from the prior stage and prepares it for the next handoff.

Postgres Persistence

Step 2: Postgres Persistence receives structured context from the prior stage and prepares it for the next handoff.

Web Inbox

Step 3: Web Inbox receives structured context from the prior stage and prepares it for the next handoff.

Human Review

Step 4: Human Review receives structured context from the prior stage and prepares it for the next handoff.

Signed Webhook

Step 5: Signed Webhook receives structured context from the prior stage and prepares it for the next handoff.

Escalation & Timeout

Step 6: Escalation & Timeout receives structured context from the prior stage and prepares it for the next handoff.

When to use

Agent workflows that need human approval at critical decision points - payments, destructive ops, legal sign-off.
Production deployments where agent restarts must not lose pending approval requests - VekInbox persists to Postgres.
Teams operating multiple agent frameworks (LangGraph, CrewAI, custom) that need a shared human review layer across all of them.
Regulated environments where every approval must be auditable with timestamps, reviewer identity, and the full request context.
Agent workflows where the human reviewer might be away from their desk - escalation policies ensure requests don't stall forever.

Not for

Single-turn approval widgets embedded in an app - VekInbox is designed for agent-native asynchronous approval flows with webhook resume.
Situations where every tool call needs human approval - use LexShield for pre-execution policy enforcement (CHALLENGE verdicts) instead of post-hoc approval.
Low-latency scenarios where waiting for human review would block the workflow - use escalation auto-deny or DEFER to secondary verifiers.

Features

Durable Postgres persistence - requests survive agent restarts, server reboots, and network failures

Wait-for-resolution - SDK blocks (with timeout) until a decision is made, via polling or webhooks

Signed webhooks - resumeWebhook fires with HMAC-SHA256 signature on resolution

Idempotent creation - key-based idempotency prevents duplicate requests for the same action

Timeout and escalation policies - declarative delay, escalation, and notification rules per request type

Multi-channel review - built-in web inbox, CLI, email notifications (Slack coming)

Multi-tenant workspaces - isolate agents, requests, and channel configurations

Cross-framework SDKs - @latticeag/vekinbox (TypeScript) and vekinbox (Python)

Self-hostable via Docker Compose with a single command (~5 min)

Full audit trail - every request, verdict, and escalation logged with timestamps and reviewer identity

Framework-agnostic - works with LangGraph, CrewAI, OpenAI Agents SDK, or any custom agent that can call an API

Declarative policy steps - same policy language for any request shape

Install and usage

usage.sh

# Start VekInbox with Docker Compose
git clone https://github.com/LatticeAG/VekInbox.git
cd VekInbox
cp .env.example .env
docker compose up --build

# API is ready when health returns ok
curl http://localhost:3001/health
# -> {"status":"ok"}

# First start seeds demo data and prints an API key (shown only once)
docker compose logs api | grep "API Key"

# Create a request from your agent (TypeScript)
npm install @latticeag/vekinbox

import { VekInbox } from "@latticeag/vekinbox";

const inbox = new VekInbox({
  apiKey: process.env.VEKINBOX_API_KEY,
  baseUrl: "http://localhost:3001/v1",
});

const request = await inbox.requests.create({
  workspaceId: "ws_...",
  agentId: "agent_...",
  key: "invoice.pay.001",
  title: "Approve $450 invoice payment?",
  resumeWebhook: "https://my-agent.example.com/resume",
});

// Wait for human resolution
const result = await inbox.requests.waitForResolution(request.id, { timeout: "1h" });
if (result.status === "approved") {
  console.log("Approved - proceeding");
}

# Python SDK
cd packages/sdk-python && pip install -e .
from vekinbox import VekInbox
inbox = VekInbox(api_key="vk_live_...", base_url="http://localhost:3001/v1")
req = inbox.requests.create(CreateRequestInput(workspace_id="ws_...", key="deploy.prod.001", title="Deploy to production?"))
result = inbox.requests.wait_for_resolution(req.id, timeout="1h")

Architecture explorer

Problem

Solution

View on GitHub

VekInbox

Quick start

Problem

Solution

How it works

Technical architecture

When to use

Not for

Features

Install and usage

Architecture explorer

Problem

Solution

Related products