# BoxClaw SDK

[![PyPI version](https://badge.fury.io/py/boxclaw.svg)](https://badge.fury.io/py/boxclaw)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Zero-Trust Runtime Execution Sandboxing for AI Agents**

The `boxclaw` SDK acts as the execution-environment boundary for LLMs operating inside agent frameworks (like OpenClaw, LangChain, or custom OpenAI scripts). By wrapping standard Python operations in our native OS-Hooks (`sys.addaudithook`), any AI acting through the functions decorated with our `@boxclaw_guardrail` must provide mathematical or deterministic proof that its intended behavior adheres to local security invariants.

This is fundamentally different from semantic guardrails: BoxClaw catches the OS system calls, FFI loads (like `ctypes`), network requests, and filesystem writes at the CPython Virtual Machine level.

## Installation

```bash
pip install boxclaw
```

## Usage

```python
from boxclaw import boxclaw_guardrail

# Bind directly between your Agent framework and BoxClaw Platform
@boxclaw_guardrail(agent_id="bot-01", required_capabilities=["network_send"])
def fetch_from_web():
    # If the network boundary token is approved, this works
    ...

@boxclaw_guardrail(agent_id="bot-02", required_capabilities=["network_send"])
def bad_agent_action():
    # Because bot-02 lacked "write_fs" capabilities, the following OS call is blocked deterministically.
    with open("hacked.txt", "w") as f:
         f.write("...")
```

## Capabilities 
- **`system_execute`**: Blocks arbitrary subprocess commands
- **`network_send`**: Blocks unauthorized HTTP/socket connections
- **`write_fs`**: Prevents the agent from modifying the filesystem
- **`ffi_load`**: Mathematically blocks C-Extensions / `ctypes` escapes

## Links
* **PyPI Package**: [https://pypi.org/project/boxclaw/](https://pypi.org/project/boxclaw/)
* **GitHub Repository**: [https://github.com/paulinebourigault/boxclaw](https://github.com/paulinebourigault/boxclaw)
