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

> Explore VulnClaw REPL TUI and Web UI differences. Understand contrasting tech stacks and interaction models for this security tool while leveraging the same core engine.

- Repository: [Unclecheng/VulnClaw](https://github.com/Unclecheng-li/VulnClaw)
- Tags: architecture
- Published: 2026-06-30

---

**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`](https://github.com/Unclecheng-li/VulnClaw/blob/main/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`](https://github.com/Unclecheng-li/VulnClaw/blob/main/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:

```bash

# Default entry – launches the interactive TUI

vulnclaw

```

Or explicitly:

```bash
vulnclaw repl

```

The command reaches `vulnclaw/cli/main.py → run_tui()`, which bridges to [`vulnclaw/cli/tui_textual.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/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`](https://github.com/Unclecheng-li/VulnClaw/blob/main/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:

```bash

# Starts FastAPI on 0.0.0.0:8000

vulnclaw web

```

Or manually:

```bash
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`](https://github.com/Unclecheng-li/VulnClaw/blob/main/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`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/cli/tui.py).
- **VulnClaw Web UI** operates as a FastAPI server defined in [`vulnclaw/web/app.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/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`](https://github.com/Unclecheng-li/VulnClaw/blob/main/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`](https://github.com/Unclecheng-li/VulnClaw/blob/main/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`](https://github.com/Unclecheng-li/VulnClaw/blob/main/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.