sandbox-agent-sdk 0.1.4

Python client SDK for Sandbox Agent — universal API for automatic coding agents in sandboxes

sandboxagent

Python client SDK for Sandbox Agent — the universal API for automatic coding agents in sandboxes.

Installation

pip install sandbox-agent-sdk

Quick Start

import asyncio
from sandboxagent import SandboxAgent

async def main():
    # Connect to a running sandbox-agent server
    agent = await SandboxAgent.connect("http://localhost:2468")
    
    # Check health
    health = await agent.health()
    print(f"Health: {health}")
    
    # Filesystem operations
    await agent.write_file("/tmp/hello.txt", "Hello from Python!")
    content = await agent.read_file("/tmp/hello.txt")
    print(f"File content: {content}")
    
    # Run a process
    result = await agent.run_process({
        "command": "/bin/echo",
        "args": ["hello", "world"],
        "cwd": "/tmp"
    })
    print(f"stdout: {result['stdout']}")
    
    # List available agents
    agents = await agent.list_agents()
    print(f"Available agents: {[a['id'] for a in agents]}")
    
    # Get inspector URL
    print(f"Inspector: {agent.inspector_url}")
    
    await agent.dispose()

asyncio.run(main())

Starting a Local Server

from sandboxagent import SandboxAgent

# Download and start a local sandbox-agent binary
agent = await SandboxAgent.start()
print(f"Server running at {agent._base_url}")
print(f"Inspector: {agent.inspector_url}")

# ... use the agent ...

await agent.dispose()

ACP Sessions

# Create an ACP session with an agent
session = await agent.create_session(agent="claude")

# Send a prompt
response = await session.prompt("Write a Python function to calculate factorial")
print(response)

# Configure session settings
await session.set_model("claude-sonnet-4-20250514")
await session.set_mode("code")

# Destroy the session
await agent.destroy_session(session.id)

Workspace Configuration

Inject config files and environment variables into sandboxes during startup:

from sandboxagent import SandboxAgent
from sandboxagent.workspace_config import WorkspaceConfig

# Generate config content
auth_content = WorkspaceConfig.auth_json({
    "openai_api_key": "sk-...",
    "anthropic_api_key": "sk-ant-..."
})

# Start sandbox with workspace files
agent = await SandboxAgent.start(
    workspace_files={
        "auth.json": auth_content,
        ".env": "API_KEY=secret\nDEBUG=1"
    },
    workspace_env={"FOO": "bar"}
)

API Coverage

Core APIs

• Health: health(), wait_for_health()
• Filesystem: read_file(), write_file(), list_entries(), stat(), move(), delete_entry(), mkdir_fs()
• Processes: create_process(), run_process(), list_processes(), get_process(), stop_process(), kill_process(), delete_process()
• Agents: list_agents(), get_agent(), install_agent()
• Config: get_mcp_config(), set_mcp_config(), get_skills_config(), set_skills_config(), get_process_config(), set_process_config()

Session Management

• create_session(), resume_session(), destroy_session(), list_sessions(), get_session()
• Session helpers: prompt(), set_model(), set_mode(), set_thought_level(), set_config_option()

Process Helpers

• Logs: follow_process_logs() — SSE streaming with log subscription
• Terminal: connect_process_terminal() — WebSocket interactive terminal

Sandbox Lifecycle

• pause_sandbox(), resume_sandbox(), restart_sandbox(), destroy_sandbox(), kill_sandbox()

Development

# Setup
uv sync

# Run tests
uv run pytest

# Run integration tests (requires local server)
uv run pytest -m integration

# Lint and format
uv run ruff check
uv run ruff format

# Type check
uv run mypy sandboxagent

License

Apache-2.0