Command Guard

The Command Guard wraps shell execution with security checks. It validates commands against the Sandbox before running them and enforces timeouts.

Setup

guard.py

from veska import CommandGuard, Sandbox

sandbox = Sandbox(project_root="/home/user/my-project")
guard = CommandGuard(sandbox=sandbox, timeout=60)  # 60s default timeout

Running commands

run.py

# Run a command as a specific agent
result = await guard.run("backend", "python app.py")

if result.success:
    print(result.stdout)
else:
    if result.blocked:
        print(f"Blocked: {result.block_reason}")
    else:
        print(f"Failed: {result.stderr}")
        print(f"Exit code: {result.return_code}")

CommandResult

python

CommandResult(
    success: bool,            # Command completed successfully
    stdout: str = "",         # Standard output
    stderr: str = "",         # Standard error
    return_code: int = 0,     # Process exit code
    blocked: bool = False,    # True if sandbox blocked it
    block_reason: str = "",   # Why it was blocked
)

Working directory

By default, commands run in the agent's territory. You can override with cwd:

cwd.py

# Runs in agent's territory
await guard.run("backend", "ls")

# Override working directory (still checked by sandbox)
await guard.run("backend", "ls", cwd="/home/user/my-project/backend/src")

# Custom timeout
await guard.run("backend", "pytest", timeout=120)