Vengtoo Agent

Lightweight authorization sidecar for AI agents, APIs, and microservices.

Open-source. Self-hostable. No vendor lock-in.

The Vengtoo Agent runs alongside your services and makes authorization decisions locally with sub-millisecond latency. It pulls policies from Vengtoo Cloud (or loads them from a local file), evaluates requests against the authorization engine in-memory, and returns allow/deny decisions without network round-trips on the hot path.

What it does

• Serves POST /access/v1/evaluation with sub-millisecond decision latency — no per-request calls to the cloud
• Syncs policy bundles automatically from Vengtoo Cloud on a configurable interval
• Caches bundles to disk for instant warm restarts (no downtime during deploys or cloud outages)
• Exposes Prometheus metrics, structured decision logs, and health endpoints out of the box

Quick Start

Install

Docker (recommended): vengtoo/agent on Docker Hub.

docker pull vengtoo/agent:latest

Go install:

go install github.com/vengtoo/agent/cmd/agent@latest

Binary download:

Grab the latest release from GitHub Releases for your platform (linux/amd64, linux/arm64, darwin/arm64).

Configure

Create vengtoo-agent.yaml (or set environment variables):

api_key: "your-vengtoo-api-key"
cloud_url: "https://api.vengtoo.com"
listen_addr: "0.0.0.0:8181"
poll_interval: "30s"

Run

# With config file
vengtoo-agent --config ./vengtoo-agent.yml

# With env vars
VENGTOO_API_KEY=your-key vengtoo-agent

# With Docker
docker run -d \
  -e VENGTOO_API_KEY=your-key \
  -p 8181:8181 \
  -v vengtoo-cache:/var/lib/vengtoo/bundles \
  vengtoo/agent:latest

Test with curl

# Allowed request
curl -s -X POST http://localhost:8181/access/v1/evaluation \
  -H "Content-Type: application/json" \
  -d '{
    "subject": { "type": "agent", "id": "ai-assistant" },
    "resource": { "type": "mcp_tool", "name": "database__query" },
    "action": { "name": "invoke" }
  }'

{
  "allowed": true,
  "reason": "Access granted via role",
  "access_path": "role"
}

# Denied request — AI agent tries to drop a table
curl -s -X POST http://localhost:8181/access/v1/evaluation \
  -H "Content-Type: application/json" \
  -d '{
    "subject": { "type": "agent", "id": "ai-assistant" },
    "resource": { "type": "mcp_tool", "name": "database__execute", "attributes": { "sql": "DROP TABLE users" } },
    "action": { "name": "invoke" }
  }'

{
  "allowed": false,
  "reason": "BLOCKED: DROP operations are not permitted for AI agents"
}

Configuration

The agent loads config from YAML (--config <path>, ./vengtoo-agent.yaml, or ~/.vengtoo/agent.yaml). Environment variables override YAML values.

Env var	YAML key	Default	Description
VENGTOO_API_KEY	api_key	— (required for cloud mode)	API key from Vengtoo Cloud
VENGTOO_CLIENT_SECRET	client_secret	—	When set, requires Authorization: Bearer <secret> on /access/v1/evaluation.
VENGTOO_CLOUD_URL	cloud_url	https://api.vengtoo.com	Vengtoo Cloud base URL
VENGTOO_TENANT_ID	tenant_id	(auto-resolved)	Tenant ID; auto-detected from bundle if not set
VENGTOO_LISTEN_ADDR	listen_addr	0.0.0.0:8181	HTTP listen address
VENGTOO_POLL_INTERVAL	poll_interval	30s	How often to sync policies from the cloud
VENGTOO_CACHE_DIR	cache_dir	~/.vengtoo/bundles	Directory for persisted policy bundles
VENGTOO_LOG_LEVEL	log_level	info	Log verbosity (debug, info, warn, error)
VENGTOO_DECISION_LOG	decision_log	false	Enable structured JSON decision logging to stdout
VENGTOO_AGENT_NAME	agent_name	hostname	Identifies this agent instance in the dashboard
VENGTOO_AGENT_REGION	agent_region	—	Display label for the region this agent runs in
VENGTOO_AGENT_DOMAIN	agent_domain	—	Display label for the domain or environment
VENGTOO_HEARTBEAT_INTERVAL	heartbeat_interval	30s	How often the agent sends a liveness ping to cloud
VENGTOO_AUDIT_FORWARDING	audit_forwarding	true	Forward decisions to cloud Decision Log
VENGTOO_AUDIT_ENDPOINT	audit_endpoint	derived from cloud_url	Override the audit ingest endpoint
VENGTOO_AUDIT_BATCH_SIZE	audit_batch_size	100	Decision events to buffer before flushing
VENGTOO_AUDIT_BATCH_INTERVAL	audit_batch_interval	5s	Maximum wait before flushing a partial batch
VENGTOO_AUDIT_BUFFER_SIZE	audit_buffer_size	10000	In-memory buffer capacity for decision events
VENGTOO_AUDIT_RETRY_ATTEMPTS	audit_retry_attempts	5	Retry attempts for failed audit log flushes
VENGTOO_TRUSTED_KEYS_PATH	trusted_keys_path	~/.vengtoo/trusted_keys.json	Pinned public keys for bundle signature verification
VENGTOO_BUNDLE_SIGNATURE_REQUIRED	bundle_signature_required	false	Reject unsigned bundles — set true for strict verification
VENGTOO_AGENT_HOSTING	agent_hosting	self	Hosting label shown in the dashboard (self, aws, gcp, etc.)

Modes

Cloud mode (default)

The agent connects to Vengtoo Cloud, pulls your tenant's policy bundle, and keeps it synced on the configured interval. This is the standard production deployment.

VENGTOO_API_KEY=your-key vengtoo-agent

Local mode

Load policies from a local .rego file instead of the cloud. No API key or cloud account required.

vengtoo-agent --policy ./examples/policy.rego

See examples/policy.rego for a starter policy.

Local mode is useful for:

• Self-hosted deployments without cloud dependency
• CI/CD pipeline testing
• Policy authoring and iteration

Health and Observability

Endpoints

Endpoint	Purpose
POST /access/v1/evaluation	Single authorization check. Returns { allowed, reason, access_path }.
POST /access/v1/evaluations	Batch authorization — evaluate multiple subject/resource/action tuples in one request.
GET /.well-known/authzen-configuration	AuthZEN 1.0 discovery endpoint.
GET /healthz	Liveness check. Returns 200 while the process is running. Includes bundle revision, sync age, and degraded status.
GET /readyz	Readiness check. Returns 200 once a policy bundle is loaded (from cache or cloud). Returns 503 until ready.
GET /metrics	Prometheus metrics (decisions total, latency histogram, sync status, degraded state).

Decision logging

Enable structured decision logs for auditing and debugging:

VENGTOO_DECISION_LOG=true vengtoo-agent

Each /access/v1/evaluation call emits a JSON log line:

{
  "time": "2026-04-19T14:03:11.482Z",
  "level": "INFO",
  "msg": "decision",
  "subject_id": "user-123",
  "resource_id": "doc-456",
  "action": "view",
  "decision": true,
  "reason": "Access granted via role",
  "access_path": "role",
  "ms": 0.42
}

Key metrics

Metric	Type	Description
vengtoo_agent_decisions_total	counter	Total authorization decisions (by allowed, access_path)
vengtoo_agent_decision_duration_seconds	histogram	Evaluation latency
vengtoo_agent_degraded	gauge	1 when serving from stale cache
vengtoo_agent_bundle_last_sync_timestamp_seconds	gauge	Unix timestamp of last successful sync

MCP Gateway

Using AI agents with MCP (Claude Code, Cursor, VS Code, GitHub Copilot)? The Vengtoo MCP Gateway sits in front of your MCP servers and uses the Vengtoo Agent to authorize every tool call before it executes.

Feedback

• GitHub Issues — Bug reports and feature requests
• Documentation — Guides and API reference

License

Apache-2.0 — see LICENSE.