Vexa Agent Control 开源 AI 智能体安全网关进入公开预览

📌 Table of Contents

• Overview
• Why Vexa Agent Control
• Key Capabilities
• Supported Ecosystem
• Quickstart
  • Option A: Standalone Developer Workstation (CLI)
  • Option B: Universal LLM Gateway (OpenAI / Python / cURL)
  • Option C: Team Hub & Web Console (Docker Compose)
  • Option D: Standalone Docker Proxy
• Architecture & Data Flow
• Declarative Policy Specification
• CLI Reference & Day-to-Day Operations
• Production & Cloud Deployment
• Security, Privacy & Sovereign Independence
• Documentation Index
• Community & Support
• Public Preview Feedback

💡 Overview

Vexa Agent Control is an ultra-fast, open-source security gateway and transparent runtime proxy purpose-built for AI agents, developer IDEs, and enterprise platform teams. It intercepts Model Context Protocol (MCP) and HTTP/LLM communications to provide deterministic safety, secret protection, token economics, and tamper-evident auditability in sub-millisecond execution times.

Two Flexible Operating Modes:

1. Workstation Sentry & MCP Firewall: Runs locally (127.0.0.1:18080) as a zero-overhead transparent sidecar. Natively wraps coding assistants (Cursor, Claude Desktop, Claude Code, Codex, Antigravity, VS Code) to enforce parameter sanitization, loop prevention, and secret redacting before any payload leaves the machine.
2. Centralized Enterprise AI Gateway: Deploys in your private VPC or cloud cluster to unify upstream model routing (OpenAI, Anthropic, Azure, Google Gemini, Groq, AWS Bedrock, Ollama) behind a single OpenAI-compatible endpoint with virtual key custody, spend caps, and SIEM streaming.

Warning

Public Preview Notice & Scoped Guarantees: Vexa Agent Control is currently in public preview. This release is intended for developer testing, experimental local proxying, and controlled evaluation environments. It is not yet rated for high-risk autonomous production side-effects without operator oversight. See Public Preview Scope & Known Limitations for full details.

⚖️ Why Vexa Agent Control

🚀 Key Capabilities

  ┌──────────────────────────────────────────────────────────────────────────────────────┐
  │                           Developer IDEs & AI Agents                                 │
  │           Cursor · Claude Code · Claude Desktop · Antigravity · Codex · VS Code      │
  └──────────────────────────────────────────┬───────────────────────────────────────────┘
                                             │ Wire / MCP / HTTP Proxy (18080)
                                             │ X-Request-ID · W3C traceparent
                                             ▼
  ┌──────────────────────────────────────────────────────────────────────────────────────┐
  │                    VEXA AGENT CONTROL GATEWAY (Pure Rust Engine)                     │
  │  ├─ 🔒 20+ Pattern DLP & Credential Redactor (Regex · Entropy · BIP-39 · Luhn)       │
  │  ├─ 🧠 Deterministic Heuristic Prompt Injection Shield                               │
  │  ├─ ⚡ Dual-Tier Semantic Vector Cache (L1 SHA-256 exact + L2 Cosine Vector / Qdrant) │
  │  ├─ 🛡️ Zero-Trust MCP Tool Firewall & Path Traversal Validator (<64MB RSS)           │
  │  └─ 📜 Tamper-Evident HMAC-SHA256 Audit Stream (non-blocking SIEM fan-out)           │
  └──────────────────────────────────────────┬───────────────────────────────────────────┘
                                             │ Scoped Virtual Key (mTLS)
                                             ▼
  ┌──────────────────────────────────────────────────────────────────────────────────────┐
  │              GO CONTROL-PLANE BROKER — Authoritative LLM Request Authority           │
  │                                                                                      │
  │  1. Ingress & Trace Validation   ──► Validate / assign RequestID & W3C traceparent  │
  │  2. Identity & Security Gate     ──► Tenant · Model Allowlist · DLP · Residency     │
  │  3. LLM Router Engine            ──► Active RouteProfile: Primary + max 1 Fallback  │
  │  4. Preflight Spend Auth         ──► Reserve ceiling across all route candidates     │
  │  5. Authoritative Broker Loop    ──► max 2 attempts · Jittered backoff · Deadline   │
  │     ├─► Attempt 1 (Primary)      ──► Dispatch · Pre-commit retry barrier            │
  │     │   └─ If 503/429/Timeout    ──► Classify · Check deadline · Proceed to #2     │
  │     └─► Attempt 2 (Fallback)     ──► Dispatch · Settle spend · Finalize dossier     │
  │  6. Request Dossier              ──► broker_requests + broker_attempts (PostgreSQL)  │
  │                                                                                      │
  └──────────┬──────────────────────────────────────────────────────────┬───────────────┘
             │                                                          │
             ▼                                                          ▼
  ┌──────────────────────────────────┐       ┌─────────────────────────────────────────┐
  │      Upstream LLM Providers      │       │    Vexa Control Hub (1-Region Topology) │
  │  ✅ OpenAI  ✅ Anthropic Claude  │       │  PostgreSQL · route_profiles            │
  │  ✅ Google Gemini                │       │  broker_requests · broker_attempts       │
  │  ℹ️  Azure · Groq · Bedrock      │       │  Web Console · OIDC SSO · Key Vault     │
  │  ℹ️  Local / Ollama              │       │  Multi-factor /readyz Probe             │
  └──────────────────────────────────┘       └─────────────────────────────────────────┘

✅ = P0 Verified Auto-Failover (OpenAI, Anthropic, Gemini) · ℹ️ = Path-Specific (P0 primary only) Topology: Single-region production deployment. Brokered requests: max 2 attempts (Primary + 1 Fallback), fail-closed.

• Universal OpenAI-Compatible LLM Gateway: Drop-in routing for /v1/chat/completions and /v1/models. Translates schemas seamlessly between OpenAI, Anthropic, Gemini, Groq, Bedrock, and Ollama.
• Transparent Workstation Sentry: 1-command connection and atomic rollback for local developer assistants with zero manual proxy configuration.
• Enterprise Semantic Vector Caching: Built-in L1 exact SHA-256 and L2 vector cosine similarity engine (in-memory or Qdrant) delivering sub-3ms responses and 100% token cost elimination on repeated queries.
• Fail-Closed Spend Governance: Enforces microcent rate caps, concurrent connection ceilings, and 500ms upstream cancellation on client disconnects.
• Scoped Virtual Keys: Issue admin-governed developer tokens with model allowlists, spend caps, and CIDR network boundaries without distributing live provider credentials.
• Decoupled Trace Store & Immutable Audit Outbox (Phase 0a Baseline): Parallel analytical trace graph (traces.db) joined to cryptographic HMAC audit logs (audit.jsonl), preserving historical verification via frozen AuditEntryV1Legacy schemas (ADR-009).
• Idempotent 6-State HITL Engine: Server-side atomic CAS state machine (PENDING → RESERVED → EXECUTING → EXECUTED / OUTCOME_UNKNOWN) with idempotency keys and secret isolation preventing replay attacks and crash ambiguities (ADR-010).
• Cross-Platform Parity: First-class native execution across Windows (Named Pipes, DPAPI, Services), Linux (Unix Domain Sockets, systemd --user, 0600 modes), and macOS (UDS, launchd, Keychain).
• Explicit Host Threat Boundary: Complete transparent disclosure of protection domains (protecting against rogue agents, prompt injection, and browser CSRF/DNS rebinding while documenting local same-user OS boundaries) in our Threat Model.

🔌 Supported Ecosystem

Upstream LLM Providers & Routing Tiers

Vexa Agent Control provides transparent proxying and central broker governance across leading LLM providers. In accordance with the P0 Reliability & Safe Operations standard, provider capabilities are organized by verified tier:

Operating Standard: Centrally brokered requests execute an authoritative, bounded retry loop (Primary + max 1 Fallback, max 2 attempts total) with W3C traceparent correlation, atomic preflight spend ceilings, and fail-closed security. Auto-failover is tested and verified across OpenAI, Anthropic Claude, and Google Gemini adapters.

Supported Coding Assistants & Protection Profiles (FR-P0-1)

Security Posture Definitions (PRD FR-P0-1):

• ENFORCED: Affirmatively inspected and blocked before downstream execution.
• OBSERVED: Inspected in shadow mode; operations permitted.
• UNCOVERED: No interception path exists for this route (e.g. direct cloud egress or native OS shell commands). Layer with container/OS isolation.
• UNKNOWN / UNHEALTHY: Proxy daemon offline, configuration drifted, or unmanaged.

⚡ Quickstart

Option A: Standalone Developer Workstation (CLI)

Run a complete local MCP firewall, inline DLP secret redaction, and developer dashboard on your machine in under 2 minutes (100% offline, zero cloud dependency, no account required):

Step 1: Install the Standalone Binary

macOS / Linux / WSL (Bash/Zsh):

curl -fsSL https://raw.githubusercontent.com/noviqtechnologies/Vexa-Agent-Control/main/install/install.sh | bash
export PATH="$HOME/.local/bin:$PATH"
agentcontrol --version

Windows (PowerShell):

irm https://raw.githubusercontent.com/noviqtechnologies/Vexa-Agent-Control/main/install/install.ps1 | iex
agentcontrol.exe --version

Step 2: Configure Upstream Model Provider & Start Gateway

Set your upstream LLM provider API key (or point to local models like Ollama/LM Studio):

PowerShell (Windows):

$env:OPENAI_API_KEY = "sk-proj-..."
# or: $env:ANTHROPIC_API_KEY = "sk-ant-..."
agentcontrol.exe start --standalone

Bash / Zsh (macOS / Linux):

export OPENAI_API_KEY="sk-proj-..."
# or: export ANTHROPIC_API_KEY="sk-ant-..."
agentcontrol start --standalone

(Alternatively, add OPENAI_API_KEY=sk-proj-... to a .env file in your working directory, or run local engines like Ollama on http://localhost:11434 / LM Studio).

Tip

Add --standalone (or set AGENTCONTROL_STANDALONE=true) for local, offline development to run the gateway self-contained without connecting to an external or central Control Hub.

Note

Keep this terminal open or run it as a service. The proxy actively intercepts local tool calls, enforces DLP & prompt security, and serves the developer dashboard on loopback (http://127.0.0.1:18080).

Step 3: Open the Local Developer Dashboard

Open your web browser and navigate to: 👉 http://127.0.0.1:18080

You will see the "This Device" dashboard displaying active listener health, loaded DLP patterns, and an event feed waiting for agent traffic.

Step 4: Connect Your AI Coding Assistant

In a new terminal window, connect the AI coding assistant(s) installed on your machine:

# Connect Cursor IDE:
agentcontrol connect cursor

# Connect Claude Desktop (MCP stdio-proxy):
agentcontrol connect claude

# Connect Claude Code (CLI / terminal):
agentcontrol connect claude-code

# Connect Google Antigravity IDE:
agentcontrol connect antigravity

# Connect OpenAI Codex CLI:
agentcontrol connect codex

# Connect VS Code (Continue extension):
agentcontrol connect vscode-continue

What happens behind the scenes: Agent Control writes a safe, cryptographically hashed ownership manifest (~/.agentcontrol/manifests/<client>.manifest.json) and points your IDE's MCP and LLM routing to 127.0.0.1:18080.

Tip

Each client is a distinct target. claude = Claude Desktop (stdio); claude-code = Claude Code CLI terminal; vscode-continue = VS Code Continue extension.

Step 5: Verify Active Posture & Live Telemetry

1. Check your connected assistants and gateway health:

agentcontrol status     # Inspect target capability vectors & LLM routing
agentcontrol clients    # List all detected vs protected clients
agentcontrol doctor     # Run read-only diagnostic checks (returns 0 if healthy)

1. Now, prompt your AI assistant in Cursor, Claude, or Codex. Watch prompts, token counts, and DLP redactions immediately stream live across your open dashboard at http://127.0.0.1:18080!

Step 6: Non-Destructive Disconnect & Cleanup

Whenever you wish to return your IDE configurations to their pristine original state:

# Cleanly restore original client configurations anytime:
agentcontrol disconnect cursor
agentcontrol disconnect claude        # Claude Desktop
agentcontrol disconnect claude-code  # Claude Code CLI
agentcontrol disconnect antigravity
agentcontrol disconnect codex
agentcontrol disconnect vscode-continue

Option B: Universal LLM Gateway (OpenAI / Python / cURL)

Point your existing OpenAI SDK client directly to Vexa Agent Control to gain automatic DLP scanning, spend caps, and semantic vector caching:

Python Example

from openai import OpenAI

# Point client to Vexa Agent Control Gateway
client = OpenAI(
    base_url="http://localhost:18080/v1",
    api_key="your-vexa-virtual-key" # or provider key in local_compat mode
)

response = client.chat.completions.create(
    model="anthropic/claude-3-7-sonnet-20250219", # Auto-translated & routed
    messages=[
        {"role": "system", "content": "You are a secure coding assistant."},
        {"role": "user", "content": "Scan this repository for security risks."}
    ],
    temperature=0.2,
    stream=True
)

for chunk in response:
    content = chunk.choices[0].delta.content
    if content:
        print(content, end="", flush=True)

cURL Example

curl -X POST http://localhost:18080/v1/chat/completions \
  -H "Authorization: Bearer your-vexa-virtual-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Review authorization policies."}],
    "temperature": 0.0
  }'

Option C: Team Hub & Web Console (Docker Compose)

Deploy the complete centralized control plane (PostgreSQL, Go Control Plane API, React Management Console, and Security Gateway):

git clone https://github.com/noviqtechnologies/Vexa-Agent-Control.git
cd Vexa-Agent-Control

# Configure local environment
cp .env.team.example .env

# Launch full team stack
docker compose -f docker-compose.team.yml up -d

Developer Workstation Enrollment to Team Hub:

# Authenticate workstation via browser SSO and enroll machine identity with the Hub:
agentcontrol login --hub http://localhost:18081
agentcontrol connect cursor

Option D: Standalone Docker Proxy

Run a zero-dependency, non-root (UID 10001) proxy bound strictly to loopback (127.0.0.1:18080):

docker compose -f docker-compose.standalone.yml up -d

🏛️ Architecture & Data Flow

Vexa Agent Control operates across 4 coordinated architectural planes:

1. Edge Execution Plane (Developer Workstation):
   • Background daemon listens strictly on loopback (127.0.0.1:18080), zero elevation required.
   • stdio-proxy child processes enforce memory RSS ceilings (< 64MB) and 60s timeouts per MCP server.
   • Authoritative OwnershipManifest guarantees 100% non-destructive, reversible client config changes.
   • OS-native authenticated IPC (Windows Named Pipe with SID DACL; POSIX unix socket 0600).
2. Gateway Broker Plane (Rust Proxy Core):
   • High-throughput asynchronous Hyper 1.0 engine with sub-millisecond evaluation overhead per request.
   • Dual-tier semantic vector cache resolves repeated queries in ~2.4ms (L1 SHA-256 + L2 Cosine Vector).
   • Inline 21-pattern DLP scanner, prompt injection heuristics, and MCP tool path-traversal firewall.
   • Forwards centrally brokered requests upstream to the Go Control-Plane Broker via scoped virtual keys.
3. Control-Plane Broker & Governance Plane (Go — 1-Region Topology):
   • Authoritative LLM Router Engine: Resolves active versioned RouteProfile for each brokered request (Primary + max 1 Fallback, max 2 attempts, configurable deadline_ms).
   • Bounded Retry Loop: Classifies upstream errors (retryable: 502/503/504/429 within deadline; non-retryable: 400/401/403/spend denial) with full-jitter backoff. Retry is prohibited once the first downstream SSE byte is committed.
   • Preflight Spend Reservation: Reserves microcent ceiling across all eligible route candidates before any egress; single idempotent settlement after completion.
   • Request Dossier Store: Every brokered request and its ordered attempt records are persisted in PostgreSQL (broker_requests, broker_attempts) with W3C traceparent correlation and complete secret scrubbing.
   • Multi-factor /readyz Probe: Validates DB, active route profile, spend service, audit outbox, and at least one eligible provider route before accepting live traffic.
   • Multi-tenant PostgreSQL with BSD Valkey distributed state. OIDC identity binding (Google Workspace, Entra ID, Okta, Auth0, Keycloak). Cryptographically signed Ed25519 policy distributions.
4. Audit & Analytics Plane:
   • Sequential HMAC-SHA256 hash-chained tamper-evident audit ledger (audit.jsonl) — committed to disk via sync_all() before confirming each request.
   • Non-blocking asynchronous fanout to enterprise SIEM platforms (Splunk HEC, Datadog, OpenSearch).
   • Complete request dossiers queryable via GET /api/v1/observability/request-logs/{id}/dossier.

📜 Declarative Policy Specification

Policies are defined in standard GitOps-friendly YAML (agentcontrol-policy.yaml):

version: "2"
default_action: deny

# LLM Provider Controls & Whitelisting
llm:
  providers:
    - name: "openai"
      action: "allow"
      models: ["gpt-4o*", "o1*", "o3*"]
      max_tokens_per_request: 4096
    - name: "anthropic"
      action: "allow"
      models: ["claude-3-7*", "claude-3-5*"]
  
  # Inline Data Loss Prevention
  dlp:
    actions:
      - entity: "AWS_KEY"
        action: "deny"
      - entity: "OPENAI_KEY"
        action: "deny"
      - entity: "SSH_KEY"
        action: "deny"
      - entity: "CREDIT_CARD"
        action: "deny"

  # Enterprise Semantic Vector Caching
  semantic_cache:
    enabled: true
    similarity_threshold: 0.88
    backend: "in_memory" # "in_memory" | "qdrant"
    embedder:
      engine: "local"

# Microcent Budget Governance
spend_caps:
  enabled: true
  concurrency_ceiling: 50
  max_tokens_per_session: 100000

# MCP Tool Sandboxing & Path Traversal Guards
tools:
  - name: "read_file"
    action: allow
    parameters:
      - name: "path"
        type: string
        required: true
        validators:
          - path_traversal

🖥️ Unified UI Experience Across Workstation & Fleet

Vexa Agent Control provides a seamless, unified governance interface designed for two distinct scopes:

┌────────────────────────────────────────────────────────────────────────────────────────┐
│                                 VEXA AGENT CONTROL UI                                  │
├───────────────────────────────────────────┬────────────────────────────────────────────┤
│ 💻 THIS DEVICE (`127.0.0.1:18080`)        │ 🏢 TEAM HUB (`localhost:18300` / Cloud)    │
│ • Local Workstation Developer Dashboard   │ • Multi-Workstation Fleet Governance       │
│ • Zero External Dependencies (Embedded)   │ • Organization SSO & Policy Distribution   │
│ • Live SSE Traffic & DLP Redactions       │ • Global Spend Caps & Virtual Key Vault    │
│ • Interactive HITL Approval Prompts       │ • Multi-Agent Audits & SIEM Export         │
│ • Client Connection & Port Posture        │ • Centralized SOC 2 / ISO 27001 Dossiers   │
└───────────────────────────────────────────┴────────────────────────────────────────────┘

🛠️ Complete CLI Reference & Operations

The agentcontrol CLI conforms strictly to PRD §12, providing deterministic, cross-platform lifecycle commands:

☁️ Production & Cloud Deployment

Deploy Vexa Agent Control to your production infrastructure using enterprise-grade infrastructure-as-code:

1. Kubernetes (Helm Chart)

Deploy scalable gateway pods with sidecar injection and native Horizontal Pod Autoscaling:

# Option A: Official Vexa Helm Repository
helm repo add vexa https://charts.vexasec.io
helm repo update
helm install agentcontrol vexa/agentcontrol -n agentcontrol-system --create-namespace

# Option B: Local Repository Checkout
helm install agentcontrol ./chart -f ./chart/values.yaml -n agentcontrol-system --create-namespace

# Option C: OCI Registry (GHCR)
helm install agentcontrol oci://ghcr.io/noviqtechnologies/charts/agentcontrol -n agentcontrol-system --create-namespace

Read the Kubernetes Guide →

2. Multi-Cloud OpenTofu / Terraform

Production blueprints with ~$0–$25/mo baseline cost:

• AWS ECS Fargate: Spot task execution, ALB, AWS Secrets Manager (infra/aws)
• Azure Container Apps: Scale-to-zero microservices with built-in Envoy ingress (infra/azure)
• Google Cloud Run (v2): Multi-container revisions with Secret Manager integration (infra/gcp)

🔒 Security, Privacy & Sovereign Independence

• 100% Free & Open-Source Core: Released under the permissive Apache 2.0 License.
• Zero Telemetry Guarantee: Absolutely no tracking pings, metrics exfiltration, or cloud phone-home in standalone mode. Your prompts, code, and credentials remain 100% within your perimeter.
• Zero Private Key Ingestion: Workstations generate Ed25519 device keypairs locally in OS hardware/secure storage (DPAPI/Keychain). Private keys never leave the host.
• Cryptographic Audit Chain: Every single log entry in audit.jsonl is linked via HMAC-SHA256 hash chaining to guarantee tamper-evidence.
• Continuity Guarantee: Read our Continuity & Sovereign Guarantee detailing why your team will never be stranded or locked in.

📚 Documentation Index

Explore the complete Documentation Hub:

• Getting Started: 10-Minute Developer Quickstart · Workstation Guide · Docker Deployment
• Integration Guides: Integrations Matrix · Cursor · Claude Desktop · Claude Code · Antigravity · Codex · Custom Python/TS Agents
• Enterprise & Governance: Team Hub Guide · Organization Admin & Virtual Keys · OIDC Identity Binding · SIEM Forwarding · Kubernetes Helm
• Technical Reference: CLI Commands · Policy Configuration · Architecture Decision Records (ADRs) · Host Threat Model · Audit Threat Model · Troubleshooting

⚠️ Public Preview Scope & Known Limitations

Vexa Agent Control is provided as a developer public preview. While core security components are tested with automated regression suites across Windows, macOS, and Linux, prospective evaluators should be aware of the following operational boundaries:

1. Same-User Process Boundaries: The workstation daemon binds to 127.0.0.1:18080. Host processes running with the same local OS user account can access loopback connections. For hostile multi-tenant local environments, container bridge mode or dedicated OS user isolation is required.
2. Human-in-the-Loop (HITL) Guarantees:
   • Approval requests write append-only state transitions to the durable WAL (hitl_wal.jsonl).
   • If the daemon crashes during tool execution, recovery guarantees that uncertain side effects are marked OUTCOME_UNKNOWN rather than silently re-executed.
   • PERMANENT_ALLOW is explicitly prohibited in preview builds; durable exceptions must be made via auditable policy configuration files in version control.
3. Hardware & Benchmark Evidence: All release receipts (target/benchmark_release_receipt.json) are generated directly from live Criterion runs and security precision/recall evaluation.
4. Tested Platform Matrix:
   • Linux: Ubuntu 20.04 / 22.04 / 24.04 (x86_64, aarch64)
   • macOS: macOS 13 / 14 / 15 (Apple Silicon M-series, Intel x86_64)
   • Windows: Windows 10 / 11 / Server 2022 (x86_64)

📣 Public Preview Feedback

Important

Vexa Agent Control is currently in public preview. Your feedback directly influences what we build next.

We want to hear about your experience — whether it's a missing integration, a policy edge case, a UX rough edge, or a feature you wish existed. Every submission is read by the core team.

👉 Share Feedback via the Public Preview Form

Specifically we'd love to know:

• Integrations — Are there coding assistants or LLM providers we should prioritize?
• Policies — Are the default DLP patterns too aggressive or missing key patterns for your stack?
• Operations — What's the hardest part of deploying or managing Vexa Agent Control in your team?
• Security — Are there threat vectors or compliance requirements we should address sooner?

💬 Community & Support

• 💬 Discord: Join the Vexa Community
• 🐞 GitHub Issues: Report Bugs & Request Features
• 🔒 Security Advisories: SECURITY.md · Report Vulnerability
• 🏢 Enterprise Inquiries: contact@vexasec.io · vexasec.io