zachos-agent-sandbox-sdk 0.1.0

Sandboxed execution environments for AI agents with permission management and audit logging

agent-sandbox-sdk

Give AI agents controlled system access without the security nightmares or container overhead.

What is this?

agent-sandbox-sdk is a Python SDK that wraps AI agent functions in isolated execution environments with fine-grained permission controls, resource limits, and comprehensive audit logging. Instead of giving LLMs unrestricted system access or wrestling with Docker containers, you get a simple decorator-based API that makes sandboxing as easy as @sandbox(permissions=[...]).

Perfect for LangChain tools, CrewAI agents, or any AI system that needs to touch the filesystem, network, or spawn processes safely.

Features

• Decorator-based API – Wrap any function with @sandbox() for instant isolation
• Fine-grained permissions – Whitelist specific filesystem paths, network domains, and process types
• Resource limits – Cap CPU time, memory usage, and disk writes per execution
• Comprehensive audit logging – Track every action with timestamps, results, and resource consumption
• Real-time monitoring – Built-in dashboard for observing agent behavior across sessions
• Framework integrations – Drop-in support for LangChain, CrewAI, and AutoGPT
• Webhook support – Get notified on permission violations or resource threshold breaches
• Cross-platform – Works on Linux, macOS, and Windows

Quick Start

Installation

pip install agent-sandbox-sdk

Basic Usage

from agent_sandbox import sandbox, FileSystemPermission, NetworkPermission

@sandbox(
    permissions=[
        FileSystemPermission(read=["/data"], write=["/tmp/output"]),
        NetworkPermission(domains=["api.example.com"])
    ],
    max_execution_time=30,  # seconds
    max_memory_mb=512
)
def agent_task(query: str):
    # Agent code runs in isolated environment
    with open("/data/docs.txt") as f:
        content = f.read()
    
    # Network access only to whitelisted domains
    response = requests.get("https://api.example.com/search")
    
    return process_results(content, response.json())

# Execute safely
result = agent_task("analyze sales data")

LangChain Integration

from langchain.agents import Tool
from agent_sandbox.integrations.langchain import SandboxedTool

# Wrap any LangChain tool with sandbox protection
safe_tool = SandboxedTool(
    tool=Tool(
        name="file_reader",
        func=read_file,
        description="Read files from disk"
    ),
    permissions=[FileSystemPermission(read=["/safe/path"])],
    max_execution_time=10
)

agent = initialize_agent([safe_tool], llm, agent="zero-shot-react-description")

Monitoring Dashboard

# Start the monitoring dashboard
agent-sandbox dashboard --port 8080

Access at http://localhost:8080 to view:

• Real-time agent execution logs
• Resource usage graphs
• Permission violation alerts
• Audit trail exports

Usage Examples

Resource Monitoring

from agent_sandbox import sandbox, get_execution_stats

@sandbox(max_memory_mb=256, max_execution_time=60)
def data_processor(files: list):
    results = []
    for file in files:
        results.append(process_file(file))
    return results

result = data_processor(["data1.csv", "data2.csv"])
stats = get_execution_stats()

print(f"Peak memory: {stats.peak_memory_mb}MB")
print(f"Execution time: {stats.execution_time}s")
print(f"Files accessed: {stats.files_accessed}")

Audit Logging

from agent_sandbox import sandbox, AuditLogger

# Configure audit logger with webhook
logger = AuditLogger(
    log_file="/var/log/agents/audit.jsonl",
    webhook_url="https://your-server.com/audit-webhook",
    alert_on_violation=True
)

@sandbox(
    permissions=[NetworkPermission(domains=["safe-api.com"])],
    audit_logger=logger
)
def agent_action():
    # All actions logged automatically
    response = requests.get("https://safe-api.com/data")
    return response.json()

CrewAI Integration

from crewai import Agent, Task, Crew
from agent_sandbox.integrations.crewai import SandboxedAgent

# Create sandboxed CrewAI agent
analyst = SandboxedAgent(
    role="Data Analyst",
    goal="Analyze sales data",
    backstory="Expert in data analysis",
    permissions=[
        FileSystemPermission(read=["/data/sales"]),
        NetworkPermission(domains=["api.salesforce.com"])
    ],
    max_execution_time=120
)

crew = Crew(agents=[analyst], tasks=[...])

Tech Stack

• Core: Python 3.8+ with asyncio for concurrent execution
• Isolation: Platform-specific syscall monitoring (seccomp on Linux, Seatbelt on macOS)
• Dashboard: FastAPI backend with React frontend
• Audit Storage: SQLite for local logging with optional PostgreSQL support
• Monitoring: Prometheus metrics export for production observability

Configuration

Create sandbox_config.yaml:

default_permissions:
  filesystem:
    read: ["/data/public"]
    write: ["/tmp"]
  network:
    domains: ["*.safe-api.com"]
  
resource_limits:
  max_execution_time: 60
  max_memory_mb: 512
  max_disk_write_mb: 100

audit:
  enabled: true
  log_file: "/var/log/agent_sandbox/audit.log"
  webhook_url: "https://monitoring.example.com/webhook"
  
dashboard:
  port: 8080
  auth_required: true

CLI Commands

# Start monitoring dashboard
agent-sandbox dashboard

# View audit logs
agent-sandbox logs --tail 100 --filter "violation"

# Export audit report
agent-sandbox export --format json --output report.json

# Validate permissions config
agent-sandbox validate config.yaml

License

MIT License - see LICENSE file for details.

---

Security Note: This SDK provides defense-in-depth for AI agent execution but should not be the only security measure. Always follow the principle of least privilege and conduct security reviews of agent code.