obol-sdk 0.3.0
Trust infrastructure for AI agents
License: MIT
Requires Python: >=3.10
Keywords: ai agents trust monitoring security anomaly-detection

# Obol

**Trust infrastructure for AI agents.**

Obol monitors your AI agents: records what they do, scores trustworthiness, and detects anomalous behavior -- all on-device. Only categorical shapes (never paths, commands, or content) are sent to the cloud for cross-org threat intelligence.

Python 3.10+. Zero required dependencies.

Website: [obol.grayowlresearch.com](https://obol.grayowlresearch.com)

## Installation

```bash
pip install obol-sdk
```

For encrypted local audit logs (optional):

```bash
pip install obol-sdk[crypto]
```

## Quick Start

### 1. Sign up

Go to [obol.grayowlresearch.com](https://obol.grayowlresearch.com) and click **Sign Up**. Verify your email, then log in. Open the **Dashboard** and copy your API key.

### 2. Run setup

```bash
obol setup <your_api_key>
```

This single command saves your API key, scans for AI agents on your machine, registers them with Obol, and installs monitoring hooks automatically.

### 3. Verify installation

```bash
obol diagnose
```

You should see all checks passing:

```
  OBOL DIAGNOSTICS
  Verifying installation and coverage

  [1/6] Configuration
        ~/.obol/config.json exists
        API key: ob_live_xxx...xxxx
        Enforcement mode: audit

  [2/6] API Connection
        Connected to https://obol.grayowlresearch.com/v1
        1 agent(s) registered
  ...
  All checks passed. Obol is properly configured.
```

### 4. Use your agent

That's it. Use your AI agent normally -- Obol monitors in the background. View activity:

```bash
obol tail --agent 1    # Live event stream
obol events            # Recent events
obol status            # Overview dashboard
```

## Supported Agents

| Agent | Support | Setup |
|-------|---------|-------|
| Claude Code | Native hooks | Automatic via `obol setup` |
| Cursor | Native hooks | Automatic via `obol setup` |
| Windsurf | Native hooks | Automatic via `obol setup` |
| Aider | Wrap mode | `obol wrap -- aider` |
| Open Interpreter | Wrap mode | `obol wrap -- interpreter` |
| Any command | Wrap mode | `obol wrap -- <command>` |

## Claude Agent SDK Integration

For agents built on the Claude Agent SDK, use `ObolAgent` to add PreToolUse and PostToolUse monitoring hooks directly:

```python
from obol.agent_sdk import ObolAgent

agent = ObolAgent(api_key="ob_live_...")

# Use as hooks in your Agent SDK pipeline
# PreToolUse: enforcement gate (blocks in enforce mode if lockdown active)
# PostToolUse: monitoring, anomaly detection, event logging
```

`ObolAgent` uses the same detection engine and ML classifier as the CLI hooks. It plugs into the Agent SDK's hook system without requiring external processes.

## Framework Interceptors

Obol provides interceptors for popular agent frameworks. Each interceptor runs the full on-device detection engine before every tool call, and can block dangerous operations in enforce mode.

Install with the framework extra you need:

```bash
pip install obol-sdk[langchain]       # LangChain
pip install obol-sdk[crewai]          # CrewAI
pip install obol-sdk[openai-agents]   # OpenAI Agents SDK
pip install obol-sdk[openai]          # OpenAI Chat Completions
pip install obol-sdk[autogen]         # AutoGen
```

### LangChain

```python
from obol.interceptors import langchain
langchain.install()

# All BaseTool.invoke() and ainvoke() calls are now monitored.
# In enforce mode, ObolSecurityBlock is raised for dangerous calls.
```

### OpenAI Agents SDK

```python
from obol.interceptors.openai_agents import ObolRunHooks
from agents import Runner

hooks = ObolRunHooks()  # reads enforcement_mode from ~/.obol/config.json
result = await Runner.run(agent, input="...", hooks=hooks)

# Or override enforcement mode:
hooks = ObolRunHooks(enforcement_mode="enforce")
```

### CrewAI

```python
from obol.interceptors import crewai
crewai.install()

# Patches Agent.execute_task() and Crew.kickoff().
```

### Auto-Instrument All Frameworks

```python
import obol
obol.auto_instrument()  # Detects and patches all installed frameworks
```

Or set `OBOL_AUTO_INSTRUMENT=1` in your environment to instrument on import.

## Enforcement Modes

Obol starts in **audit mode** by default. You control the level:

| Mode | Behavior |
|------|----------|
| `audit` | Log all actions, detect anomalies. Never block. Default. |
| `alert` | Audit + desktop notifications on threats. |
| `enforce` | Alert + auto-lockdown on critical events. |

Change mode:

```bash
obol config set enforcement_mode alert
```

## CLI Reference

```bash
# Setup and account
obol setup <api_key>            # One-command install
obol whoami                     # Account info and status
obol diagnose                   # Verify installation

# Monitoring
obol status                     # Overview dashboard
obol agents                     # List your agents
obol events --agent 5           # View events for agent
obol tail --agent 5             # Live event stream

# Security
obol alerts                     # View security alerts
obol unlock                     # Remove lockdown (enforce mode)
obol retry                      # Resend failed events from local fallback

# Configuration
obol config show                # Current settings
obol config set KEY VALUE       # Change setting
obol disable                    # Temporarily disable monitoring
obol enable                     # Re-enable monitoring
```

## Configuration

### Environment Variables

| Variable | Purpose |
|----------|---------|
| `OBOL_API_KEY` | API key (alternative to config file) |
| `OBOL_API_URL` | API endpoint override (default: `https://obol.grayowlresearch.com/v1`) |

### Config File

Location: `~/.obol/config.json`

```json
{
  "api_key": "ob_live_...",
  "api_url": "https://obol.grayowlresearch.com/v1",
  "enforcement_mode": "audit",
  "agents": { ... }
}
```

The config file is created automatically by `obol setup`. Environment variables take precedence over config file values.

## Privacy

All detection runs **on your machine**. Obol sends only **categorical shapes** to the cloud for cross-org threat intelligence:

- Action type (bash, read, write, etc.)
- Target category (e.g., "credential_ssh", "source_code", "unknown_external" -- never the actual path or URL)
- Content hash (not content)
- Timing information

No file paths, URLs, command text, or content ever leaves your machine. Full audit logs stay in `~/.obol/audit/`.

## Troubleshooting

**Cloudflare blocks API requests.**
The default Python `urllib` User-Agent is blocked by Cloudflare. Obol's HTTP client sets `User-Agent: obol-sdk/0.1.0` automatically. If you are making direct API calls, set the User-Agent header explicitly.

**Hooks not running.**
Run `obol diagnose` to check hook installation. If hooks are missing, run `obol setup <key>` again. Verify hook files exist at `~/.obol/handler.py` and `~/.obol/gate.py` (both should be read-only, mode 444).

**Agent not being monitored.**
Check that your agent appears in `obol agents`. If not, `obol setup` may not have detected it. For unsupported agents, use `obol wrap -- <command>`.

**Nothing is being blocked.**
The default enforcement mode is `audit`, which logs but never blocks. To enable blocking, set enforce mode: `obol config set enforcement_mode enforce`.

**Config file location.**
All Obol configuration is stored in `~/.obol/config.json`. Audit logs are in `~/.obol/audit/`. Failed events (when the API is unreachable) are buffered in `~/.obol/failed_events.jsonl`.

**API connection issues.**
Run `obol diagnose` to test connectivity. If the API is unreachable, events are buffered locally and can be retried with `obol retry`. Check that `OBOL_API_URL` or `api_url` in config points to `https://obol.grayowlresearch.com/v1`.

## Links

- Website: [obol.grayowlresearch.com](https://obol.grayowlresearch.com)
- Dashboard: [obol.grayowlresearch.com/dashboard](https://obol.grayowlresearch.com/dashboard)

## License

MIT License. Copyright Gray Owl Research, LLC.