MantisBox Documentation

Complete guide to configuring and using MantisBox for AI agent governance.

Installation

MantisBox is an OpenClaw plugin. Install it alongside your OpenClaw setup:

Terminal

# Clone the repository
git clone https://github.com/JurassiCrafter/mantisbox
cd mantisbox

# Install dependencies and build
pnpm install
pnpm build

Then add MantisBox to your OpenClaw configuration.

Configuration

Add MantisBox to your ~/.openclaw/openclaw.json:

~/.openclaw/openclaw.json

{
  "plugins": {
    "paths": ["/path/to/mantisbox"],
    "entries": {
      "mantisbox": {
        "enabled": true,
        "config": {
          "defaultMode": "execute-with-approval",
          "approvalTimeoutMs": 300000,
          "webEnabled": true,
          "webPort": 7777,
          "alwaysAllowTools": ["read", "web_search"],
          "alwaysBlockTools": []
        }
      }
    }
  }
}

Quick Start

After installation, restart your OpenClaw gateway:

Terminal

# Restart the gateway to load MantisBox
openclaw gateway restart

# Check MantisBox status
openclaw mantisbox

# Open the web dashboard
open http://localhost:7777

MantisBox will now intercept all tool calls and apply governance rules.

Classification

MantisBox classifies every tool call into one of four risk levels:

📖

Read-Only

Inspection only, no side effects. File reads, searches, status checks.

🔄

Reversible

Can be undone. File writes, config changes, soft deletes.

💥

Destructive

Cannot be undone. Hard deletes, data wipes, permanent changes.

🔐

Privileged

Elevated access or external communication. Emails, API calls, sudo.

Classification is automatic based on tool name and parameters. You can override classifications in config.

Autonomy Modes

Control how MantisBox handles tool calls with four autonomy modes:

Mode	Behavior	Use Case
`observe`	Log everything, execute nothing	Understanding agent behavior
`propose`	All actions require approval	Maximum control
`execute-with-approval`	Safe actions auto-approve, risky wait	Recommended default
`fully-autonomous`	Execute everything, log only	Trusted environments

Change modes via CLI or web dashboard:

Terminal

openclaw mantisbox:mode execute-with-approval

Approval Gates

When an action requires approval, MantisBox:

Blocks the tool call
Sends a notification (web dashboard, Discord, etc.)
Waits for approval or timeout
Proceeds or blocks based on decision

Approve pending requests via CLI:

Terminal

# List pending approvals
openclaw mantisbox:pending

# Approve a request
openclaw mantisbox:approve <id>

# Deny a request
openclaw mantisbox:deny <id> "reason"

Kill Switch

Emergency halt for all agent execution:

Terminal

# Activate kill switch
openclaw mantisbox:kill "emergency maintenance"

# Resume operations
openclaw mantisbox:resume

The kill switch immediately blocks all tool calls and cancels pending approvals.

Audit Log

Every tool call is logged with full context:

Terminal

# View recent audit entries
openclaw mantisbox:audit 20

# Get audit statistics
openclaw mantisbox:stats

Audit logs are stored in JSONL format at ~/.mantisbox/audit.jsonl.

Rules Engine

Define pattern-based rules for fine-grained control:

Config Example

{
  "config": {
    "alwaysAllowTools": ["read", "web_search", "memory_get"],
    "alwaysBlockTools": ["dangerous_tool"],
    "allowedPaths": ["/Users/*/workspace/*"],
    "blockedPaths": ["/etc/*", "/System/*"],
    "rules": [
      {
        "tool": "exec",
        "params": { "command": "^git\\s" },
        "action": "allow",
        "reason": "Git commands are safe"
      }
    ]
  }
}

Web Dashboard

MantisBox includes a real-time web dashboard at http://localhost:7777:

Status Overview — Mode, kill switch, statistics
Pending Approvals — Approve/deny with one click
Audit Log — Browse all tool calls
Real-time Updates — SSE-powered live updates

Configure the dashboard in your config:

Config

{
  "webEnabled": true,
  "webPort": 7777,
  "webHost": "127.0.0.1"
}

CLI Commands

Command	Description
`openclaw mantisbox`	Show current status
`openclaw mantisbox:mode [mode]`	Get or set autonomy mode
`openclaw mantisbox:kill [reason]`	Activate kill switch
`openclaw mantisbox:resume`	Deactivate kill switch
`openclaw mantisbox:pending`	List pending approvals
`openclaw mantisbox:approve <id>`	Approve a pending action
`openclaw mantisbox:deny <id> [reason]`	Deny a pending action
`openclaw mantisbox:audit [limit]`	Show recent audit entries
`openclaw mantisbox:stats`	Show audit statistics

Config Options

Option	Type	Default	Description
`defaultMode`	string	`execute-with-approval`	Initial autonomy mode
`approvalTimeoutMs`	number	`300000`	Approval timeout (5 min)
`webEnabled`	boolean	`true`	Enable web dashboard
`webPort`	number	`7777`	Web server port
`webHost`	string	`127.0.0.1`	Web server host
`alwaysAllowTools`	string[]	`[]`	Tools that bypass governance
`alwaysBlockTools`	string[]	`[]`	Tools that are always blocked
`allowedPaths`	string[]	`[]`	Glob patterns for allowed paths
`blockedPaths`	string[]	`[]`	Glob patterns for blocked paths

API

The web dashboard exposes a REST API:

Endpoint	Method	Description
`/api/status`	GET	Get current status
`/api/pending`	GET	List pending approvals
`/api/audit`	GET	Get audit entries
`/api/approve/:id`	POST	Approve a request
`/api/deny/:id`	POST	Deny a request
`/api/kill`	POST	Activate kill switch
`/api/resume`	POST	Deactivate kill switch
`/api/mode`	POST	Set autonomy mode
`/events`	GET	SSE stream for real-time updates