Sandbox Manager Plugin

Runtime management of filesystem sandbox permissions through user commands. Grant or revoke path access dynamically during a session.

Overview

The sandbox manager allows users to dynamically control which filesystem paths the model can access during a session. It operates on a three-tiered configuration model where session-level settings have the highest precedence.

Configuration Levels

Level	Path	Precedence
Global	~/.jaato/sandbox_paths.json	Lowest
Workspace	<workspace>/.jaato/sandbox.json	Medium
Session	<workspace>/.jaato/sessions/<id>/sandbox.json	Highest

Session-level configurations can override global and workspace settings. A path denied at the session level will be blocked even if allowed globally.

User Commands

sandbox list

Displays all effective sandbox paths merged from all configuration levels. Shows the path, action (ALLOW/DENY), and source level.

sandbox add <path>

Grants access to a path for the current session only.

• Adds <path> to session's allowed_paths
• Removes from denied_paths if present
• Changes take effect immediately

sandbox remove <path>

Blocks access to a path for the current session, even if allowed at global or workspace level.

• Adds <path> to session's denied_paths
• Removes from allowed_paths if present
• Changes take effect immediately

Registry Integration

The plugin integrates with PluginRegistry for path validation:

• Allowed paths: Registered via registry.authorize_external_path()
• Denied paths: Registered via registry.deny_external_path()
• Validation: sandbox_utils.check_path_with_jaato_containment() checks denied paths first, so denial always takes precedence

Plugin Protocol

Method	Returns
get_tool_schemas()	[] (no model tools)
get_user_commands()	[UserCommand("sandbox", ...)]
get_auto_approved_tools()	["sandbox"]
get_system_instructions()	None

{
  "allowed_paths": [
    "/path/to/allow",
    {
      "path": "/another/path",
      "added_at": "2024-01-15T10:30:00Z"
    }
  ],
  "denied_paths": [
    "/path/to/deny"
  ]
}

Effective Sandbox Paths:

Path                        Action   Source
/opt/company_tools          ALLOW    global
/var/www/project/assets     ALLOW    workspace
/tmp/temp_data              ALLOW    session
/home/user/sensitive        DENY     session

from shared.plugins.sandbox_manager import create_plugin

# Create and initialize
plugin = create_plugin()
plugin.initialize({
    "session_id": "my-session-123"
})
plugin.set_workspace_path("/path/to/workspace")

# Execute commands
result = plugin._execute_sandbox_command({
    "subcommand": "add",
    "path": "/external/data"
})
# Returns: {"status": "added", "path": "...", "source": "session"}

result = plugin._execute_sandbox_command({
    "subcommand": "list"
})
# Returns: {"effective_paths": [...], "summary": {...}}

# The plugin syncs to registry automatically
# Other plugins use sandbox_utils for validation:

from shared.plugins.sandbox_utils import (
    check_path_with_jaato_containment
)

# This checks denied paths first
is_allowed = check_path_with_jaato_containment(
    path="/some/path",
    workspace_root="/workspace",
    plugin_registry=registry,  # Has deny methods
    allow_tmp=True
)