VulnClaw REPL TUI and Web UI Modes: Architecture and Usage Differences

VulnClaw ships with two independent user interfaces—a terminal-based REPL TUI and a browser-based Web UI—that share the same core scanning engine but differ in technology stack, interaction model, and deployment footprint.

VulnClaw, an open-source vulnerability scanning framework hosted at Unclecheng-li/VulnClaw, provides multiple ways to interact with its scanning capabilities. While both the REPL TUI and Web UI modes ultimately invoke the same underlying logic in vulnclaw/agent/ and vulnclaw/mcp/, they serve distinct operational scenarios ranging from quick local debugging to collaborative remote monitoring.

REPL TUI Mode: The Terminal Interface

The REPL TUI (Read-Eval-Print Loop Terminal User Interface) provides a synchronous, terminal-centric experience designed for local command-line usage. This mode launches when you run the vulnclaw command without arguments or explicitly via the repl sub-command.

Technology Stack and Implementation

The REPL TUI is built on a Python-native stack optimized for terminal rendering and interactive input:

• Rich: Handles static dashboard rendering and formatted text output (see render_tui_home in vulnclaw/cli/tui.py)
• Prompt-toolkit: Drives the "Slash" command system for interactive input handling
• Textual: Powers the full-screen, mouse-aware TUI via run_tui_textual() in vulnclaw/cli/tui_textual.py

Users interact by typing slash commands such as /target 192.168.1.10, /mode deep, and /run, or by using the legacy numeric menu. The interface updates dashboards on-the-fly and can launch scanning tasks directly from the prompt.

Launching the REPL TUI

Start the terminal interface using either the default entry point or explicit sub-command:

# Default entry – launches the interactive TUI

vulnclaw

Or explicitly:

vulnclaw repl

The command reaches vulnclaw/cli/main.py → run_tui(), which bridges to vulnclaw/cli/tui_textual.py to initialize the Textual backend.

Web UI Mode: The Browser Interface

The Web UI wraps VulnClaw's scanning engine behind a FastAPI HTTP layer, delivering a richer, browser-based experience suitable for remote access and multi-user environments.

FastAPI Architecture and Frontend Stack

The Web UI leverages an ASGI-based architecture with clear separation between backend services and frontend assets:

• FastAPI: Handles HTTP requests and routing in vulnclaw/web/app.py via the create_app factory function
• Pydantic: Validates request and response models for type-safe API interactions
• Vite-built frontend: Serves HTML, JavaScript, and CSS from frontend/dist (with fallback static folder support)
• Server-Sent Events (SSE): Streams real-time task output to browsers via GET /api/tasks/{task_id}/stream

Key API Endpoints

The Web UI exposes RESTful endpoints consumed by the browser frontend and available for programmatic access:

• GET /api/health – Service health checks
• GET /api/config – Current LLM configuration retrieval
• POST /api/tasks/run – Scan task initiation
• GET /api/tasks/{task_id}/stream – Live task output streaming (SSE)

Starting the Web UI Server

Launch the FastAPI application using the CLI wrapper or Uvicorn directly:

# Starts FastAPI on 0.0.0.0:8000

vulnclaw web

Or manually:

uvicorn vulnclaw.web.app:create_app --host 127.0.0.1 --port 8000

Navigate to http://localhost:8000/ to access the dashboard. All actions—including target selection, mode changes, and report downloads—are performed via HTTP calls.

Comparative Analysis: REPL TUI vs Web UI

Feature	REPL TUI	Web UI
Execution Environment	Direct terminal execution (stdout/stdin)	FastAPI ASGI server with HTTP endpoints
Launch Command	vulnclaw or vulnclaw repl	vulnclaw web
Entry Point	vulnclaw/cli/main.py → run_tui()	vulnclaw/web/app.py → create_app()
Interaction Model	Slash commands (/target, /mode, /run) or numeric menus	Browser clicks and HTTP API calls
Output Rendering	Rich text dashboards and prompt-toolkit widgets	JSON API responses consumed by Vite frontend
Real-time Updates	Synchronous terminal refresh	SSE streaming to browser
Use Case	Local debugging, CI pipelines, headless environments	Remote access, collaborative monitoring, visual report navigation
Extensibility	Add slash command handlers to _SLASH_HANDLERS in vulnclaw/cli/tui.py	Add FastAPI routes or service classes in vulnclaw/web/services/

When to Use Each Interface

Choose the REPL TUI when you need quick, local debugging or one-off scans in environments without graphical displays. It excels in CI/CD pipelines, SSH sessions, and situations requiring immediate terminal feedback without server overhead.

Choose the Web UI for long-running collaborative sessions where persistent web access is valuable. The browser interface supports multi-user monitoring, remote target management, and visual navigation of complex vulnerability reports that benefit from HTML rendering and interactive charts.

Summary

• VulnClaw REPL TUI runs directly in your terminal using libraries like Rich and Textual, processing slash commands synchronously through vulnclaw/cli/tui.py.
• VulnClaw Web UI operates as a FastAPI server defined in vulnclaw/web/app.py, serving a Vite-built frontend and streaming task updates via SSE.
• Both interfaces ultimately call identical core functions for task launching and diagnostics, differing only in presentation layer and protocol.
• The REPL TUI requires no additional server infrastructure, while the Web UI provides HTTP-based accessibility for distributed teams.

Frequently Asked Questions

Can I use VulnClaw without a graphical desktop environment?

Yes. The REPL TUI mode requires only a terminal with stdin/stdout support and works entirely within text-based interfaces. It is ideal for servers, containers, and SSH sessions where X11 or browser access is unavailable.

What is the difference between vulnclaw and vulnclaw web commands?

The vulnclaw command (or vulnclaw repl) launches the interactive REPL TUI directly in your terminal via run_tui() in vulnclaw/cli/main.py. The vulnclaw web command starts the Web UI FastAPI server, binding to 0.0.0.0:8000 by default and serving browser-accessible endpoints.

How do I add custom commands to VulnClaw?

For the REPL TUI, extend the _SLASH_HANDLERS dictionary in vulnclaw/cli/tui.py to register new slash command handlers. For the Web UI, implement new service classes under vulnclaw/web/services/ and expose them through additional FastAPI routes in vulnclaw/web/app.py.

Does the Web UI support real-time scanning feedback?

Yes. The Web UI utilizes Server-Sent Events (SSE) through the /api/tasks/{task_id}/stream endpoint to push live task output to connected browsers, providing real-time log updates without polling.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}