DEV Community

Cover image for V-Cyber: The Operating System AI Agents Were Waiting For
JuanCS-Dev
JuanCS-Dev

Posted on

V-Cyber: The Operating System AI Agents Were Waiting For

#ai #cybersecurity #agents #webdev

Or: Why We Built a Formula 1 Chassis When Everyone Else Was Gluing Wheels to Prompts

The Problem Nobody Wants to Admit

Have you ever watched an AI agent crash because Shodan's API returned a 429? Ever lost hours debugging why your "autonomous agent" decided to forget context mid-investigation? Welcome to the hell of LLM wrappers.

The industry sold us "autonomous agents" but delivered glorified scripts: a loop with gpt.chat(), some if/else statements, and a prayer that nothing breaks. The result? Fragile, non-deterministic systems that are impossible to audit and—let's be honest—dangerous in production environments.

V-Cyber isn't another wrapper. It's a complete Operating System for cybersecurity agents, where AI is the 1000-horsepower engine, but Python and Go code is the carbon-fiber chassis that ensures it doesn't fly off the track at 200 mph.

Architecture: OS, Not Orchestration

The Difference Between a Wrapper and an Operating System

An LLM wrapper does this:

while True:
    response = llm.chat(prompt)
    execute(response.tool_call)
Enter fullscreen mode Exit fullscreen mode

An Operating System for Agents does this:

TaskManager.register(agent_id)
EventBus.emit("agent.started")
Magistrate.validate(action, context)
await TaskManager.execute_with_checkpointing(action)
Metrics.record(latency_μs, success_rate)
Enter fullscreen mode Exit fullscreen mode

See the difference? In V-Cyber, every agent action passes through 7 validation layers before touching a real endpoint. This isn't "vibes-based computing"—it's deterministic engineering.

The Three Layers of the Chassis

1. Python Engine: Asyncio Without the Memory Leaks

Asyncio is powerful but brutal. Orphaned tasks, deadlocks, memory leaks—every Python developer has fought these battles. In V-Cyber, we built a TaskManager that registers every created task:

  • Lifecycle Tracking: Every task has state (Pending → Running → Done → Cancelled)
  • Graceful Shutdown: When you run v-cyber stop, the system doesn't kill the process. It signals each agent to checkpoint state, cancels sub-tasks, and only then shuts down.
  • Microsecond Metrics: Every operation is instrumented. Latency, success rate, retries—everything tracked.

The Pagani Standard: Zero Band-Aids

We eliminated except Exception: from the entire codebase. Every exception must be handled with specific tuples:

try:
    result = await api.call()
except (TimeoutError, HTTPError) as e:
    # Specific handling
Enter fullscreen mode Exit fullscreen mode

Why? Because except Exception is a band-aid. We don't want band-aids; we want to cure the wound. If something can fail in 5 different ways, we handle all 5 explicitly.

More: 100% Type Hints. If it doesn't pass mypy --strict, it doesn't enter main. Zero ambiguity, zero production surprises.

2. MCP Backbone: Standardizing Intelligence

The Model Context Protocol (MCP) is our bridge between LLMs and real tools. But we don't use MCP as "just another adapter"—it is the system's backbone.

FastMCP: Unified Tool Registry

Every tool in V-Cyber (Shodan, VirusTotal, OTX, Nmap):

  1. Registers in the MCP Registry
  2. Automatically converts to JSON Schema for Gemini 3
  3. Exposes via HTTP/WebSocket to the Go TUI and React Dashboard

The trick? The same tools the AI uses are what you see in the Dashboard. No duplication, no drift between "what the AI does" and "what you see".

Example: Shodan Query

When the AI decides to query Shodan:

 @mcp.tool()
async def shodan_host_lookup(ip: str) -> ShodanResult:
    # 1. Sanitization (Magistrate Phase 1)
    clean_ip = sanitize_input(ip)

    # 2. Rate limit check
    await rate_limiter.acquire("shodan")

    # 3. Execute with retry logic
    try:
        result = await shodan_client.host(clean_ip)
    except (ShodanAPIError, TimeoutError) as e:
        await TaskManager.record_failure(e)
        raise

    # 4. Emit event for Dashboard
    EventBus.emit("tool.executed", {
        "tool": "shodan",
        "target": clean_ip,
        "success": True
    })

    return result
Enter fullscreen mode Exit fullscreen mode

This isn't just "call the API and hope". It's a deterministic execution pipeline with observability at every step.

3. The Magistrate: Ethical Runtime Validation

Here's where V-Cyber diverges from every other agent platform. We don't just run tools; we evaluate them through a 7-phase Ethical Magistrate:

The 7 Phases

  1. Sanitization: Clean all inputs. No SQL injection, no command injection, no path traversal.

  2. Keyword Analysis: Detect high-risk strings (exploit, delete, rm -rf, etc.)

  3. Context Check: Is this action allowed on this specific target?

   if target.is_production and action.risk_level > RiskLevel.MEDIUM:
       raise PermissionDenied("High-risk action on production target")
Enter fullscreen mode Exit fullscreen mode

  1. Rate Limiting: Prevent API abuse and detection

  2. Blast Radius Calculation: What's the worst that could happen?

  3. Audit Logging: Every action recorded with full context

  4. L3 Human-in-the-Loop: For critical actions, the backend halts execution and emits a human_review.required event via WebSocket, waiting for approval from the Dashboard.

The Go Connection: Charm-ing the Terminal

Why Go for the TUI?

Python is great for orchestration, but for handling 1000+ events/second in a terminal UI? Go crushes it.

The Stack

  • Bubble Tea: The Elm Architecture for CLIs (immutable state, pure functions, no side effects)
  • Lipgloss: Styling that makes terminals look like modern UIs
  • HTTP/2: High-speed communication with the Python bridge

The 99% Coverage Discipline

We didn't just write tests; we built a Deterministic Test Suite:

Maximus 2.0: The Constitutional Guardian

Our pre-commit agent audits every commit against CODE_CONSTITUTION.md:

  • ✅ All exceptions explicitly typed
  • ✅ All functions have type hints
  • ✅ No print() statements (use logging)
  • ✅ Test coverage doesn't drop below 98%

Key Technical Metrics

Metric Value
Total Tests 850 (100% passing)
Code Coverage 98.99%
Average Latency 47ms (tool execution)
Architecture Modular MCP Bridge + Event Bus (SQLite Persistence)
Stack Python 3.11, Go 1.21, React 18, SQLite, FastMCP, Gemini 3 Pro

The Bottom Line

V-Cyber is what happens when you treat AI agents like mission-critical infrastructure instead of research demos.

The chassis matters as much as the engine. Maybe more.

Built by engineers who were tired of AI agents that couldn't survive production.
Written on February 16, 2026.

Top comments (0)