Metadata-Version: 2.4
Name: openclaw-sentrix
Version: 0.1.6
Summary: Sandboxed OpenClaw with agnetic police management
Project-URL: Homepage, https://openclaw-sentrix.vercel.app
Project-URL: Repository, https://github.com/openclaw/openclaw
Project-URL: Issues, https://github.com/openclaw/openclaw/issues
Author: Desmond Zee
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,ai-safety,llm,openclaw,sandbox
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Security
Requires-Python: >=3.10
Requires-Dist: click
Requires-Dist: cryptography
Requires-Dist: httpx
Requires-Dist: langchain-anthropic
Requires-Dist: langchain-core
Requires-Dist: langchain-openai
Requires-Dist: langgraph
Requires-Dist: opensandbox
Requires-Dist: opensandbox-server
Requires-Dist: pydantic>=2
Requires-Dist: python-dotenv
Requires-Dist: questionary
Requires-Dist: rich
Requires-Dist: websockets>=10
Description-Content-Type: text/markdown

# Sentrix

**Agentic police for [OpenClaw](https://github.com/openclaw/openclaw).** Sentrix uses AI agents to watch AI agents — a patrol swarm continuously monitors your OpenClaw instance for PII leaks, harmful intent, unsafe tool use, and prompt injection, then escalates flagged incidents to an automated investigator that produces case files.

## How It Works

Sentrix runs OpenClaw inside a sandboxed Docker container, captures every LLM API call, and feeds the logs into a multi-layered oversight system:

```
┌──────────────────────────────────────────────────────┐
│  Patrol Swarm (LangGraph)                            │
│    ├── Orchestrator assigns log streams              │
│    ├── N patrol agents scan in parallel              │
│    │     flags: PII · harmful intent · unsafe tools  │
│    │            prompt injection · credentials       │
│    ├── Adjudicator: quorum vote + pheromone consensus│
│    └── → patrol_flags.jsonl                          │
│                                                      │
│  Police Investigator (LangGraph)                     │
│    ├── LeadInvestigator reads flags + raw logs        │
│    ├── Classifies per crime taxonomy                 │
│    ├── Multi-round context expansion                 │
│    └── → CaseFile (reports/*.json + police.db)       │
│                                                      │
│  Escalation Queue                                    │
│    └── Priority: HIGH → MEDIUM → LOW                 │
│        Auto-invokes investigator per threshold        │
└──────────────────────────────────────────────────────┘
```

**Patrol agents** scale logarithmically — `N = ⌈1 + log₂(n)⌉` agents for `n` log streams — and coordinate via a pheromone map (ant-colony-inspired) for consensus. When a quorum of agents flags the same stream, a `PatrolFlag` is emitted. The **investigator** then reviews the flag alongside the raw log turns, classifies the incident using a crime taxonomy (PII leak, harmful intent, unsafe tool use, prompt injection, credential solicitation, secret hardcoding, confidential data disclosure), and produces a `CaseFile` with severity, evidence, and a verdict summary.

## Install

```bash
pip install openclaw-sentrix
```

### Prerequisites

> **⚠️ Docker must be installed and running.** Sentrix runs OpenClaw inside a Docker container. Install [Docker Desktop](https://docs.docker.com/get-docker/) and make sure it's running before using Sentrix.

- **Python 3.10+**
- **Docker** (running — verify with `docker info`)

## Quick Start

```bash
# Interactive setup — walks you through provider, API key, model,
# channels, patrol, and security configuration
sentrix run
```

The wizard walks you through:

1. **Provider & API key** — Anthropic, OpenAI, Google, OpenRouter, xAI, Mistral, Groq, Together AI (auto-detects keys in your environment)
2. **Model** — choose a model for your provider
3. **Reasoning** — set thinking depth (adaptive / high / low / off)
4. **Channels** — connect Telegram, Discord, Slack, WhatsApp, or Signal
5. **Web search** — configure Brave Search API key for agent tools
6. **Patrol** — enable the patrol swarm and set escalation threshold
7. **Security** — confirms secure defaults (exec denied, all agents sandboxed, pairing required)

## CLI Reference

```
sentrix run [OPTIONS]     Start sandbox + patrol + bridge; run until Ctrl+C
sentrix chat [OPTIONS]    Attach to running sandbox and chat with the agent
sentrix bridge [OPTIONS]  Run WSS bridge only (for the web UI)
sentrix build [OPTIONS]   Build the sandbox Docker image
sentrix logs [OPTIONS]    View captured API call log files
sentrix stop              Stop running containers
sentrix police            View case files and patrol flags
sentrix police investigate <FLAG_ID>  Run investigation for a patrol flag
```

### `sentrix run`


| Flag                           | Default                   | Description                                                    |
| ------------------------------ | ------------------------- | -------------------------------------------------------------- |
| `--log-dir PATH`               | `./agent_logs`            | Host directory for logs and case files                         |
| `--rotate-mins N`              | `10`                      | Log rotation interval in minutes                               |
| `--reasoning / --no-reasoning` | `on`                      | Capture reasoning/thinking tokens                              |
| `--port N`                     | `18789`                   | Gateway port                                                   |
| `--timeout N`                  | `60`                      | Sandbox timeout in minutes                                     |
| `-e KEY=VALUE`                 |                           | Extra env vars (repeatable)                                    |
| `--image TAG`                  | `sentrix-openclaw:latest` | Override sandbox image                                         |
| `--patrol`                     |                           | Enable patrol swarm                                            |
| `--escalation LEVEL`           |                           | Auto-escalate flags (`low_above`, `medium_above`, `high_only`) |
| `--nobridge`                   |                           | Skip the WSS bridge                                            |
| `--verbose`                    |                           | Verbose output                                                 |


### Patrol Swarm

When patrol is enabled (via wizard or `--patrol`), Sentrix runs a LangGraph-based safety patrol in the background:

- Reads synced agent logs from `log_dir`
- Scales patrol agents logarithmically: `N = ⌈1 + log₂(n)⌉`
- Each agent scans for: **PII/credentials**, **harmful intent**, **unsafe tool use**, **prompt injection**
- Multi-agent quorum voting produces `PatrolFlag` entries → `patrol_flags.jsonl`
- Pheromone-based coordination prevents redundant scans
- Cleared state stored in `patrol_state.db` (SQLite, WAL mode)


| Env var                       | Description                                                  |
| ----------------------------- | ------------------------------------------------------------ |
| `OPENAI_API_KEY`              | API key for patrol LLM (preferred)                           |
| `ANTHROPIC_API_KEY`           | Fallback API key for patrol LLM                              |
| `PATROL_MODEL`                | Model name (e.g. `gpt-4o-mini`, `claude-haiku-4-5-20251001`) |
| `PATROL_CONFIDENCE_THRESHOLD` | Min confidence to emit a flag (default `0.6`)                |
| `PATROL_RULESET_VERSION`      | Bump to re-review all logs                                   |
| `PATROL_MODEL_VERSION`        | Bump when changing patrol model                              |


### Police Investigator

Flags that meet the escalation threshold are queued for the **LeadInvestigator** — a LangGraph agent that:

1. Loads the flagged log turns plus adjacent files (prev/next)
2. Can request additional context (backward/forward) for up to 3 rounds
3. Classifies the incident using a crime taxonomy
4. Produces a `CaseFile` with severity (LOW → CRITICAL), evidence, and verdict

Case files are persisted to `police.db` and written as JSON reports to `agent_logs/reports/`.

View results with:

```bash
sentrix police                        # list cases and flags
sentrix police --cases                # show case files only
sentrix police --clogs                # show patrol flags
sentrix police investigate <FLAG_ID>  # manually trigger investigation
```

### `sentrix chat`

Attach to a sandbox started by `sentrix run` and interact with the OpenClaw agent directly in your terminal.


| Flag                   | Default        | Description                              |
| ---------------------- | -------------- | ---------------------------------------- |
| `--dir PATH`           | `./agent_logs` | Log directory (must match `sentrix run`) |
| `--message`, `-m TEXT` |                | Send a single message and exit           |


### Web UI (Your Claw)

> **⚠️ The web frontend is currently under development.**

The [openclaw-sentrix](https://openclaw-sentrix.vercel.app) Next.js app has a **Your Claw** tab for chatting with OpenClaw in the browser. The app connects to your local sandbox via WSS (secure WebSocket) through the bridge.

1. Start the sandbox: `sentrix run` (bridge runs automatically on port 8766)
2. Open the app → **Your Claw** → set Bridge URL to `wss://localhost:8766`

First-time cert trust: open `https://localhost:8765` and `https://localhost:8766` in your browser to accept the self-signed certificate, then click Reconnect in the app.

### Non-interactive Mode

Skip the wizard by passing API keys directly:

```bash
sentrix run -e ANTHROPIC_API_KEY=sk-ant-... -e OPENCLAW_DEFAULT_MODEL=anthropic/claude-sonnet-4-6 --patrol
```

## Security Defaults


| Setting           | Value            | Meaning                                      |
| ----------------- | ---------------- | -------------------------------------------- |
| Shell/exec access | `deny`           | Agent cannot run shell commands              |
| Filesystem        | `workspace only` | Read/write restricted to workspace           |
| Sandboxing        | `all`            | Every agent runs in a sandbox container      |
| DM policy         | `pairing`        | Unknown senders must be approved by operator |


## Architecture

```
┌─────────────────────────────────────┐
│ Host                                │
│  sentrix run                        │
│    ├── opensandbox-server           │
│    ├── create sandbox → health check│
│    ├── channel login (stream QR)    │
│    ├── log sync (periodic pull)     │
│    ├── patrol swarm (background)    │
│    ├── police investigator (queue)  │
│    ├── WSS bridge (port 8766)       │
│    └── ./agent_logs/*.json          │
│  sentrix chat (other terminal)      │
│    └── reconnect → openclaw agent   │
└────────────┬────────────────────────┘
             │ OpenSandbox SDK
┌────────────▼────────────────────────┐
│ Sandbox Container                   │
│  entrypoint.sh (gateway + collector)│
│    ├── openclaw gateway --raw-stream│
│    │    → /data/raw-stream.jsonl    │
│    └── collect_logs.py              │
│         → /data/agent_logs/*.json   │
└─────────────────────────────────────┘
```

## License

MIT

## Bugs to fix

OpenAI API key error stating anthropic,Support for kimi 2.5

Patrol need to investigate agents

Random agents spawning without sub agents (only spawn when sub agents)

Home centering and no monitors/chairs currently in UI, toggle the sprite UI open/closed

