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.
Metadata
Release files for zachos-agent-sandbox-sdk 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| zachos_agent_sandbox_sdk-0.1.0.tar.gz | 18.0 kB | Without provenance | Details for zachos_agent_sandbox_sdk-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| zachos_agent_sandbox_sdk-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for zachos_agent_sandbox_sdk-0.1.0-py3-none-any.whl |
Total release size: 36.7 kB
Release files / zachos_agent_sandbox_sdk-0.1.0.tar.gz
| Download URL | zachos_agent_sandbox_sdk-0.1.0.tar.gz |
|---|---|
| Size | 18.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
43b624dba84919688c0fb0cf282bd6b8defd2e25888f44e9b7ea182a3eb18e8f
|
|
BLAKE2b-256 checksum How to use checksums |
2cbbb49fb1e9ec9ec62ac08229fd3d1928d2d1f9f6c4c59f05f05350a21237d9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.25
|
Release files / zachos_agent_sandbox_sdk-0.1.0-py3-none-any.whl
| Download URL | zachos_agent_sandbox_sdk-0.1.0-py3-none-any.whl |
|---|---|
| Size | 18.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f8f27cd775e23520a54656ee2165521c1df2a429137447c64bfbdd90f04c8606
|
|
BLAKE2b-256 checksum How to use checksums |
9872ce911f29529cb706d2ba5ce2153ad995f17aadecef4d75cc32dfd7064938
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.25
|
Security for zachos-agent-sandbox-sdk 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.