obol-sdk 0.3.0

Trust infrastructure for AI agents

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

Installation

pip install obol-sdk

For encrypted local audit logs (optional):

pip install obol-sdk[crypto]

Quick Start

1. Sign up

Go to obol.grayowlresearch.com and click Sign Up. Verify your email, then log in. Open the Dashboard and copy your API key.

2. Run setup

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

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:

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:

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:

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

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

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

from obol.interceptors import crewai
crewai.install()

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

Auto-Instrument All Frameworks

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:

obol config set enforcement_mode alert

CLI Reference

# 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

{
  "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
• Dashboard: obol.grayowlresearch.com/dashboard

License

MIT License. Copyright Gray Owl Research, LLC.