Architecture Overview
ClawNex is an AI agent fleet Security Operations Center. It sits between agent runtimes and model providers, observes LLM traffic, applies ClawNex Shield Rules, records evidence, and gives operators a single place to understand fleet health, threats, trust boundaries, costs, and governance posture.
This page describes the public architecture at a system level. It avoids internal file paths and private implementation notes.
System Context
ClawNex is designed for hosts running OpenClaw or compatible AI agent runtimes.
AI agents
|
| OpenAI-compatible requests
v
LiteLLM proxy
|
| pre-call scan, routing, post-call logging
v
Model providers
ClawNex dashboard
|
| reads telemetry, audit, traffic, fleet, cost, and security data
v
SQLite data storeThe dashboard and LiteLLM proxy bind locally. Public VPS installs put Caddy in front of the dashboard for HTTPS, while keeping backend services on loopback.
Core Components
| Component | Purpose |
|---|---|
| ClawNex Dashboard | Operator UI, internal API, public API, authentication, audit, configuration, and reporting |
| LiteLLM Proxy | Model-provider proxy, pre-call shield hook, post-call traffic logging, provider routing |
| ClawNex Shield Rules | Built-in detection rules for prompts and responses |
| Session Watcher | Retroactive scanner for agent session logs that did not pass through the proxy path |
| Correlation Engine | Groups related events into higher-signal findings and incidents |
| Trust Audit | Maps who can reach agents, what tools are reachable, and where trust boundaries are weak |
| Host Security Scanner | Local host posture checks surfaced in Security Posture |
| SQLite Store | Local operational data, audit events, config, traffic summaries, alerts, and reports |
| Caddy | Public HTTPS reverse proxy for VPS and server-style installs |
Traffic Flow
In the normal path, an agent sends an OpenAI-compatible request to LiteLLM. LiteLLM calls the ClawNex shield before the model sees the prompt. ClawNex scans the prompt, assigns a verdict, and returns a decision.
If shield mode is OBSERVE, the request continues and the detection is logged.
If shield mode is BLOCK, prompts that reach a block verdict are rejected before the model receives them.
After the provider returns a response, ClawNex scans the output for data-leak patterns and records telemetry for traffic, cost, evidence, and alerting.
Detection Layers
ClawNex uses three detection layers:
| Layer | When It Runs | What It Does |
|---|---|---|
| Pre-call scan | Before the model sees the prompt | Can block dangerous prompts |
| Post-call scan | After the model responds | Detects possible output leaks and records evidence |
| Retroactive scan | From session logs | Finds activity that bypassed the proxy path or happened before ClawNex was installed |
This gives operators live enforcement plus after-the-fact visibility.
Data Model
ClawNex stores local operational data in SQLite. The main data groups are:
- traffic and shield scan records
- alert and incident state
- audit events
- provider and model configuration
- operator, role, session, and API key data
- trust audit results
- security scan results
- report metadata
- cost and token summaries
The public dashboard is not a hosted SaaS dependency. A standard install runs on the operator’s machine or VPS.
Trust Boundaries
The important trust boundaries are:
| Boundary | Expected Design |
|---|---|
| Public internet to dashboard | HTTPS through Caddy, RBAC enabled |
| Dashboard to LiteLLM | Localhost only |
| LiteLLM to dashboard callback | Localhost callback path |
| Dashboard to OpenClaw | Local gateway connection |
| Dashboard to model providers | Provider APIs through configured keys |
| Operator to dashboard | Session-authenticated when RBAC is enabled |
Public-facing deployments should never expose the dashboard backend port or LiteLLM port directly.
Operational Modes
| Mode | Description |
|---|---|
| Local install | Localhost-only development or single-operator use |
| Local install with RBAC | Localhost-only, but with operator login and sessions |
| VPS install | Public HTTPS, RBAC enabled, Caddy, systemd services |
| macOS server install | Public HTTPS, RBAC enabled, Caddy, launchd services |
| Break-glass | Time-limited, audited emergency bypass of shield enforcement |
Dashboard Model
The dashboard is organized around operator workflows:
- Mission Control for executive triage and top actions
- Fleet Command for instance-level readiness
- Instance Detail for one host or client
- Correlations for multi-signal threat scoring
- Blast Radius for reachability and exposure
- Security Posture for host and CVE posture
- Trust Audit for boundaries, findings, matrix, remediation, and surfaces
- Prompt Shield and Shield Tests for detection behavior
- Traffic Monitor for live request visibility
- Token & Cost Intel and Models & Cost for spend visibility
- Infrastructure for local service state
- Audit & Evidence, Executive Reports, Access Lists, and Governance for compliance workflows
Design Choices
| Decision | Why |
|---|---|
| Local-first deployment | Keeps sensitive agent telemetry under operator control |
| LiteLLM proxy path | Uses an established OpenAI-compatible proxy instead of inventing a new model router |
| SQLite | Simple single-node operation with no external database required |
| Caddy for public HTTPS | Automatic TLS and a small public edge surface |
| RBAC on public installs | Public endpoints need authentication, session controls, and audit |
| Observe before block | Operators can tune behavior before active enforcement |
| Built-in shield rules | No install-time dependency on third-party rule downloads |
Current Scope
ClawNex is built for a single-node deployment model today. That keeps installation and operations simple. Multi-node clustering, centralized storage, and containerized OpenClaw-plus-ClawNex packaging are future deployment options, not required for the current public install path.