Skip to content

feat: implement subprocess sandbox for tool execution isolation (#131) #153

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Aureliolo merged 3 commits into from
Mar 7, 2026
Merged

feat: implement subprocess sandbox for tool execution isolation (#131) #153

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
634c5dd
feat: implement subprocess sandbox for tool execution isolation (#131)
Aureliolo Mar 7, 2026
158578b
fix: harden subprocess sandbox — security, correctness, and test cove…
Aureliolo Mar 7, 2026
b7fc1ce
fix: address 31 PR review items from local agents, CodeRabbit, Gemini…
Aureliolo Mar 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 11 additions & 7 deletions DESIGN_SPEC.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1687,8 +1687,8 @@ Tool execution requires safety boundaries proportional to the risk of each tool

| Backend | Isolation | Latency | Dependencies | Status |
|---------|-----------|---------|--------------|--------|
| `SubprocessSandbox` | Process-level: timeout, restricted PATH, workspace-scoped paths | ~ms | None | M3 |
| `DockerSandbox` | Container-level: ephemeral container, mounted workspace, no network, resource limits (CPU/memory/time) | ~1-2s cold start | Docker | M3 |
| `SubprocessSandbox` | Process-level: env filtering (allowlist + denylist), restricted PATH, workspace-scoped cwd, timeout + process-group kill, library injection var blocking | ~ms | None | **Implemented** |
| `DockerSandbox` | Container-level: ephemeral container, mounted workspace, no network, resource limits (CPU/memory/time) | ~1-2s cold start | Docker | Planned |
Comment thread
coderabbitai[bot] marked this conversation as resolved.
| `K8sSandbox` | Pod-level: per-agent containers, namespace isolation, resource quotas, network policies | ~2-5s | Kubernetes | Future |

#### Default Layered Configuration
Expand Down Expand Up @@ -2335,6 +2335,7 @@ ai-company/
│ │ │ ├── provider.py # PROVIDER_* constants
│ │ │ ├── role.py # ROLE_* constants
│ │ │ ├── routing.py # ROUTING_* constants
│ │ │ ├── sandbox.py # SANDBOX_* constants
│ │ │ ├── task.py # TASK_* constants
│ │ │ ├── template.py # TEMPLATE_* constants
│ │ │ └── tool.py # TOOL_* constants
Expand Down Expand Up @@ -2372,10 +2373,13 @@ ai-company/
│ │ ├── errors.py # Tool error hierarchy (incl. ToolPermissionDeniedError)
│ │ ├── examples/ # Example tool implementations
│ │ │ └── echo.py # Echo tool (for testing)
│ │ ├── sandbox/ # Sandboxing backends (M3)
│ │ ├── sandbox/ # Sandboxing backends
│ │ │ ├── __init__.py # Package exports
│ │ │ ├── config.py # SubprocessSandboxConfig model
│ │ │ ├── errors.py # SandboxError hierarchy
│ │ │ ├── protocol.py # SandboxBackend protocol
│ │ │ ├── subprocess.py # SubprocessSandbox (default for low-risk)
│ │ │ └── docker.py # DockerSandbox (for code_runner, terminal)
│ │ │ ├── result.py # SandboxResult model
│ │ │ └── subprocess_sandbox.py # SubprocessSandbox (default)
│ │ ├── file_system/ # Built-in file system tools
│ │ │ ├── __init__.py # Package exports
│ │ │ ├── _base_fs_tool.py # BaseFileSystemTool ABC
Expand All @@ -2385,8 +2389,8 @@ ai-company/
│ │ │ ├── list_directory.py # ListDirectoryTool
│ │ │ ├── read_file.py # ReadFileTool
│ │ │ └── write_file.py # WriteFileTool
│ │ ├── _git_base.py # Base class for git tools (workspace, subprocess)
│ │ ├── git_tools.py # Git operations — 6 built-in tools
│ │ ├── _git_base.py # Base class for git tools (workspace, subprocess, sandbox integration)
│ │ ├── git_tools.py # Git operations — 6 built-in tools (sandbox-aware)
│ │ ├── code_runner.py # Code execution (M3)
│ │ ├── web_tools.py # HTTP, search (M3)
│ │ └── mcp_bridge.py # MCP server integration (M7)
Expand Down
14 changes: 14 additions & 0 deletions src/ai_company/observability/events/sandbox.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
"""Sandbox event constants."""

from typing import Final

SANDBOX_EXECUTE_START: Final[str] = "sandbox.execute.start"
SANDBOX_EXECUTE_SUCCESS: Final[str] = "sandbox.execute.success"
SANDBOX_EXECUTE_FAILED: Final[str] = "sandbox.execute.failed"
SANDBOX_EXECUTE_TIMEOUT: Final[str] = "sandbox.execute.timeout"
SANDBOX_SPAWN_FAILED: Final[str] = "sandbox.spawn.failed"
SANDBOX_ENV_FILTERED: Final[str] = "sandbox.env.filtered"
SANDBOX_WORKSPACE_VIOLATION: Final[str] = "sandbox.workspace.violation"
SANDBOX_CLEANUP: Final[str] = "sandbox.cleanup"
SANDBOX_PATH_FALLBACK: Final[str] = "sandbox.path.fallback"
SANDBOX_HEALTH_CHECK: Final[str] = "sandbox.health_check"
16 changes: 16 additions & 0 deletions src/ai_company/tools/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,15 @@
from .invoker import ToolInvoker
from .permissions import ToolPermissionChecker
from .registry import ToolRegistry
from .sandbox import (
SandboxBackend,
SandboxError,
SandboxResult,
SandboxStartError,
SandboxTimeoutError,
SubprocessSandbox,
SubprocessSandboxConfig,
)

__all__ = [
"BaseFileSystemTool",
Expand All @@ -45,6 +54,13 @@
"ListDirectoryTool",
"PathValidator",
"ReadFileTool",
"SandboxBackend",
"SandboxError",
"SandboxResult",
"SandboxStartError",
"SandboxTimeoutError",
"SubprocessSandbox",
"SubprocessSandboxConfig",
"ToolError",
"ToolExecutionError",
"ToolExecutionResult",
Expand Down
Loading
Loading