Sandbox

The Sandbox enforces a 3-zone security model. Agents have full freedom inside their territory but are blocked from accessing framework internals or system files.

Three security zones

Zone 1 — Framework

Fully locked. No agent can read or modify framework code.

Zone 2 — Project

Full freedom inside own territory. Read-only access to other agents' territories.

Zone 3 — System

Fully blocked. No access to system files, commands, or resources.

Setup

sandbox.py

from veska import Sandbox

sandbox = Sandbox(
    project_root="/home/user/my-project",
    framework_root="/path/to/veska",  # Auto-detected if not set
)

Agent territories

territories.py

# Assign a territory to an agent
sandbox.set_territory(
    "backend",
    territory="/home/user/my-project/backend",
    read_access=["/home/user/my-project/shared"],  # Extra read paths
)

sandbox.set_territory(
    "frontend",
    territory="/home/user/my-project/frontend",
)

# Check what territory an agent has
territory = sandbox.get_territory("backend")  # Path object

Access checks

checks.py

# Check path access
result = sandbox.check_path_access("backend", "/home/user/my-project/backend/app.py", mode="write")
# SecurityResult(allowed=True, reason="Inside agent territory", zone="project")

result = sandbox.check_path_access("backend", "/etc/passwd", mode="read")
# SecurityResult(allowed=False, reason="System path blocked", zone="system")

result = sandbox.check_path_access("backend", "/home/user/my-project/frontend/index.html", mode="write")
# SecurityResult(allowed=False, reason="Not in agent territory (read-only)", zone="project")

# Check commands
result = sandbox.check_command("backend", "python app.py")
# SecurityResult(allowed=True, ...)

result = sandbox.check_command("backend", "sudo rm -rf /")
# SecurityResult(allowed=False, reason="Blocked command: sudo", zone="system")

Blocked commands

These commands are always blocked regardless of territory:

sudoshutdownrebootmkfsddmountchownrm -rf /fork bombpipe to shell

With Orchestrator

orch_sandbox.py

orchestrator = Orchestrator(
    model="claude-sonnet-4-6",
    agents=[backend, frontend],
    security={
        "project_root": "/home/user/my-project",
        "territories": {
            "backend": {"path": "backend", "read_access": ["shared"]},
            "frontend": {"path": "frontend"},
        },
    },
)