Sandbox¶
aigise.sandbox.base_sandbox ¶
logger = logging.getLogger(__name__) module-attribute ¶
BaseSandbox ¶
Bases: ABC
Base class for all sandbox implementations.
async_initialize() -> None async ¶
Initialize the sandbox.
cache_sandboxes(sandbox_instances: dict, shared_volume_id: str, cache_dir: str, task_name: str) -> dict abstractmethod classmethod ¶
Cache sandbox states and shared volume content.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sandbox_instances | dict | Dictionary mapping sandbox types to sandbox instances | required |
shared_volume_id | str | Shared volume identifier to backup | required |
cache_dir | str | Directory to store cache files | required |
task_name | str | Task name for cache naming | required |
Returns:
| Type | Description |
|---|---|
dict | Dictionary with cache results including backup paths and cached images |
copy_file_from_container(src_path: str, dst_path: str) abstractmethod ¶
Copy a file from the container to local filesystem.
copy_file_to_container(local_path: str, container_path: str) abstractmethod ¶
Copy a file from local filesystem to the container.
create_shared_volume(volume_name_prefix: str, init_data_path: Path = None, tools_top_roots: set[str] | None = None) -> tuple[str, str, str] abstractmethod classmethod ¶
Create and initialize three shared volumes.
Creates three volumes: 1. Read-only volume with sandbox scripts (mapped to /sandbox_scripts) 2. Read-write volume with user data (mapped to /shared) 3. Read-write volume with bash tools (mapped to /bash_tools)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
volume_name_prefix | str | Prefix for volume names (e.g., session_id) | required |
init_data_path | Path | Path to initial data to copy into the rw volume (optional) | None |
tools_top_roots | set[str] | None | Optional set of top-level bash_tools roots to stage. If None, stage all bash tools. | None |
Returns:
| Type | Description |
|---|---|
tuple[str, str, str] | Tuple of (scripts_volume_id, data_volume_id, tools_volume_id) |
create_single_sandbox(session_id: str, sandbox_type: str, container_config) -> Exception abstractmethod async classmethod ¶
Create a single sandbox instance asynchronously.
delete_shared_volumes(scripts_volume_id: str = None, data_volume_id: str = None, tools_volume_id: str = None) -> None abstractmethod classmethod ¶
Delete shared volumes.
ensure_ready() -> None async ¶
Ensure the sandbox is ready.
extract_file_from_container(filepath: str) -> str abstractmethod ¶
Extract file content from the container.
extract_file_from_container_bytes(filepath: str) -> bytes abstractmethod ¶
Extract file content from the container.
get_work_dir() abstractmethod ¶
Get the current working directory in the container.
launch_all_sandboxes(session_id: str, sandbox_configs: dict, shared_volume_id: str = None, scripts_volume_id: str = None, tools_volume_id: str = None) -> dict abstractmethod async classmethod ¶
Launch all sandbox instances for a session.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
session_id | str | Session identifier | required |
sandbox_configs | dict | Dictionary of sandbox_type -> ContainerConfig | required |
shared_volume_id | str | Optional shared volume to mount to all sandboxes | None |
scripts_volume_id | str | Optional scripts volume to mount to all sandboxes | None |
tools_volume_id | str | Optional tools volume to mount to all sandboxes | None |
Returns: Dictionary mapping sandbox_type to sandbox instance or connection info
run_command_in_container(command: str | list[str], timeout: int | None = None) -> tuple[str, int] abstractmethod ¶
Run a command inside the container.
wait_for_ready_or_error() -> bool async ¶
Wait for a specific sandbox to be ready or error.
ContainerConfig dataclass ¶
Lightweight config for Docker-backed sandboxes.
This is an internal convenience type to keep sandbox code tidy and typed. It intentionally mirrors common docker SDK/run options that we may support. Any unsupported fields can be kept in extra for forward-compat.
SandboxState ¶
Bases: Enum
Sandbox initialization states.
aigise.sandbox.factory ¶
Sandbox factory for creating typed sandbox instances.
SANDBOX_BACKENDS = {'native': NativeDockerSandbox, 'k8s': K8sSandbox, 'remotedocker': RemoteDockerSandbox, 'local': LocalSandbox} module-attribute ¶
SANDBOX_INITIALIZERS = {'main': MainInitializer, 'codeql': CodeQLInitializer, 'joern': JoernInitializer, 'fuzz': FuzzInitializer, 'neo4j': Neo4jInitializer, 'coverage': CoverageInitializer, 'debugger': DebuggerInitializer} module-attribute ¶
BaseSandbox ¶
Bases: ABC
Base class for all sandbox implementations.
async_initialize() -> None async ¶
Initialize the sandbox.
cache_sandboxes(sandbox_instances: dict, shared_volume_id: str, cache_dir: str, task_name: str) -> dict abstractmethod classmethod ¶
Cache sandbox states and shared volume content.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sandbox_instances | dict | Dictionary mapping sandbox types to sandbox instances | required |
shared_volume_id | str | Shared volume identifier to backup | required |
cache_dir | str | Directory to store cache files | required |
task_name | str | Task name for cache naming | required |
Returns:
| Type | Description |
|---|---|
dict | Dictionary with cache results including backup paths and cached images |
copy_file_from_container(src_path: str, dst_path: str) abstractmethod ¶
Copy a file from the container to local filesystem.
copy_file_to_container(local_path: str, container_path: str) abstractmethod ¶
Copy a file from local filesystem to the container.
create_shared_volume(volume_name_prefix: str, init_data_path: Path = None, tools_top_roots: set[str] | None = None) -> tuple[str, str, str] abstractmethod classmethod ¶
Create and initialize three shared volumes.
Creates three volumes: 1. Read-only volume with sandbox scripts (mapped to /sandbox_scripts) 2. Read-write volume with user data (mapped to /shared) 3. Read-write volume with bash tools (mapped to /bash_tools)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
volume_name_prefix | str | Prefix for volume names (e.g., session_id) | required |
init_data_path | Path | Path to initial data to copy into the rw volume (optional) | None |
tools_top_roots | set[str] | None | Optional set of top-level bash_tools roots to stage. If None, stage all bash tools. | None |
Returns:
| Type | Description |
|---|---|
tuple[str, str, str] | Tuple of (scripts_volume_id, data_volume_id, tools_volume_id) |
create_single_sandbox(session_id: str, sandbox_type: str, container_config) -> Exception abstractmethod async classmethod ¶
Create a single sandbox instance asynchronously.
delete_shared_volumes(scripts_volume_id: str = None, data_volume_id: str = None, tools_volume_id: str = None) -> None abstractmethod classmethod ¶
Delete shared volumes.
ensure_ready() -> None async ¶
Ensure the sandbox is ready.
extract_file_from_container(filepath: str) -> str abstractmethod ¶
Extract file content from the container.
extract_file_from_container_bytes(filepath: str) -> bytes abstractmethod ¶
Extract file content from the container.
get_work_dir() abstractmethod ¶
Get the current working directory in the container.
launch_all_sandboxes(session_id: str, sandbox_configs: dict, shared_volume_id: str = None, scripts_volume_id: str = None, tools_volume_id: str = None) -> dict abstractmethod async classmethod ¶
Launch all sandbox instances for a session.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
session_id | str | Session identifier | required |
sandbox_configs | dict | Dictionary of sandbox_type -> ContainerConfig | required |
shared_volume_id | str | Optional shared volume to mount to all sandboxes | None |
scripts_volume_id | str | Optional scripts volume to mount to all sandboxes | None |
tools_volume_id | str | Optional tools volume to mount to all sandboxes | None |
Returns: Dictionary mapping sandbox_type to sandbox instance or connection info
run_command_in_container(command: str | list[str], timeout: int | None = None) -> tuple[str, int] abstractmethod ¶
Run a command inside the container.
wait_for_ready_or_error() -> bool async ¶
Wait for a specific sandbox to be ready or error.
CodeQLInitializer ¶
Bases: SandboxInitializer
Initializer that initializes CodeQL static analysis capabilities to sandboxes.
async_initialize(all_sandboxes: dict[str, BaseSandbox]) -> None async ¶
Initialize sandbox initializer (async version).
CoverageInitializer ¶
Bases: SandboxInitializer
Initializer that initializes coverage capabilities to sandboxes.
async_initialize(all_sandboxes: dict[str, BaseSandbox]) -> None async ¶
Initialize sandbox initializer (async version).
DebuggerInitializer ¶
Bases: SandboxInitializer
Initializer for debugger sandboxes to compile debug binaries.
async_initialize(all_sandboxes: dict[str, BaseSandbox]) -> None async ¶
Initialize sandbox initializer (async version).
FuzzInitializer ¶
Bases: SandboxInitializer
Initializer that initializes fuzzing capabilities to sandboxes.
async_initialize(all_sandboxes: dict[str, BaseSandbox]) -> None async ¶
Initialize sandbox initializer (async version).
JoernInitializer ¶
Bases: SandboxInitializer
Initializer that initializes Joern code analysis capabilities to sandboxes.
async_initialize(all_sandboxes: dict[str, BaseSandbox]) -> None async ¶
Initialize sandbox initializer (async version).
K8sSandbox ¶
Bases: BaseSandbox
K8s sandbox representing a specific container within a Pod.
__init__(container_config: ContainerConfig, session_id: str = None, backend_type: str = None, sandbox_type: str = None, pod_name: str = None, container_name: str = None) ¶
Initialize K8sSandbox.
async_initialize() -> None async ¶
Initialize the sandbox.
create_shared_volume(volume_name_prefix: str, init_data_path: Path = None, tools_top_roots: set[str] | None = None) -> tuple[str, str, str] classmethod ¶
Create and initialize three shared PVCs.
Creates three PVCs: 1. Read-only PVC with sandbox scripts (mapped to /sandbox_scripts) 2. Read-write PVC with user data (mapped to /shared) 3. Read-write PVC with bash tools (mapped to /bash_tools)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
volume_name_prefix | str | Prefix for PVC names (e.g., session_id) | required |
init_data_path | Path | Path to initial data to copy into the rw PVC (optional) | None |
tools_top_roots | set[str] | None | Optional set of top-level bash_tools roots to stage. If None, stage all bash tools (built-in + plugins). | None |
Returns:
| Type | Description |
|---|---|
tuple[str, str, str] | Tuple of (scripts_pvc_name, data_pvc_name, tools_pvc_name) |
delete_shared_volumes(scripts_volume_id: str = None, data_volume_id: str = None, tools_volume_id: str = None) -> None classmethod ¶
Delete shared PVCs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scripts_volume_id | str | ID of the scripts PVC to delete (with or without pvc/ prefix) | None |
data_volume_id | str | ID of the data PVC to delete (with or without pvc/ prefix) | None |
tools_volume_id | str | ID of the tools PVC to delete (with or without pvc/ prefix) | None |
ensure_ready() -> None async ¶
Ensure the sandbox is ready.
initialize_all_sandboxes(sandbox_instances: dict, *, continue_on_error: bool = False) -> dict async classmethod ¶
Initialize all sandbox instances concurrently.
This should be called after launch_all_sandboxes() and after registering any hooks.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sandbox_instances | dict | Dict of sandbox_type -> K8sSandbox instance | required |
continue_on_error | bool | If True, continue on failures and return a map of sandbox_type -> Exception | None. If False, propagate errors. | False |
wait_for_ready_or_error() -> bool async ¶
Wait for a specific sandbox to be ready or error.
LocalSandbox ¶
Bases: BaseSandbox
MainInitializer ¶
Bases: SandboxInitializer
Initializer that initializes main sandbox.
async_initialize(all_sandboxes: dict[str, BaseSandbox]) -> None async ¶
Initialize sandbox initializer (async version).
NativeDockerSandbox ¶
Bases: BaseSandbox
Native Docker sandbox implementation using direct Docker API.
__init__(container_config: ContainerConfig, session_id: str = None, backend_type: str = None, sandbox_type: str = None) ¶
Initialize NativeDockerSandbox.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
container_config | ContainerConfig | ContainerConfig options controlling container launch (must include image or container_id) | required |
async_initialize() -> None async ¶
Initialize the sandbox.
cache_sandboxes(sandbox_instances: dict, shared_volume_id: str, cache_dir: str, task_name: str) -> dict classmethod ¶
Cache Docker containers and shared volume content.
This method will: 1. Backup shared volume content to a tar.gz file 2. Commit each running container to a new image
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
session_id | Session identifier | required | |
sandbox_instances | dict | Dictionary mapping sandbox types to NativeDockerSandbox instances | required |
shared_volume_id | str | Docker volume name to backup | required |
cache_dir | str | Directory to store cache files | required |
task_name | str | Task name for naming cached resources | required |
Returns:
| Type | Description |
|---|---|
dict | Dictionary with cache results |
copy_directory_from_container(src_path: str, dst_path: str) ¶
Copy a directory from the container to local filesystem.
copy_directory_to_container(src_path: str, dst_path: str) ¶
Copy a directory from the host to the container.
copy_file_from_container(src_path: str, dst_path: str) ¶
Copy a file from the container to local filesystem.
copy_file_to_container(local_path: str, container_path: str) ¶
Copy a single file to the container.
create_shared_volume(volume_name_prefix: str, init_data_path: Path = None, tools_top_roots: set[str] | None = None) -> tuple[str, str, str] classmethod ¶
Create and initialize three shared volumes.
Creates three volumes: 1. Read-only volume with sandbox scripts (mapped to /sandbox_scripts) 2. Read-write volume with user data (mapped to /shared) 3. Read-write volume with bash tools (mapped to /bash_tools)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
volume_name_prefix | str | Prefix for volume names (e.g., session_id) | required |
init_data_path | Path | Path to initial data to copy into the rw volume (optional) | None |
tools_top_roots | set[str] | None | Optional set of top-level bash_tools roots to stage. If None, stage all bash tools (built-in + plugins). | None |
Returns:
| Type | Description |
|---|---|
tuple[str, str, str] | Tuple of (scripts_volume_id, data_volume_id, tools_volume_id) |
create_single_sandbox(session_id: str, sandbox_type: str, container_config) -> tuple[str, NativeDockerSandbox] async classmethod ¶
Create a single sandbox instance without initialization.
This method only creates the Docker container and sandbox instance. Call initialize_all_sandboxes() afterwards to initialize.
create_tar_bytes(file_content: str, arcname: str) -> bytes ¶
Pack the given file content into a tar archive.
delete_container(max_wait: int = 10) ¶
Delete the container.
delete_shared_volumes(scripts_volume_id: str = None, data_volume_id: str = None, tools_volume_id: str = None) -> None classmethod ¶
Delete shared volumes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scripts_volume_id | str | ID of the scripts volume to delete | None |
data_volume_id | str | ID of the data volume to delete | None |
tools_volume_id | str | ID of the tools volume to delete | None |
ensure_ready() -> None async ¶
Ensure the sandbox is ready.
extract_file_from_container(filepath: str) -> str ¶
Extract the content of the specified file from the container.
extract_file_from_container_bytes(filepath: str) -> bytes ¶
Extract the content of the specified file from the container as bytes.
get_file_content(filepath: str) -> str ¶
Retrieve the content of a file inside the container.
get_function_content(key: str, lang: str = 'c', line_in_func: int = -1) -> tuple[str, int, int] ¶
Retrieve the content of a specific function from a file inside the container.
get_work_dir() -> str ¶
Get the working directory of the container.
initialize_all_sandboxes(sandbox_instances: dict[str, BaseSandbox], *, continue_on_error: bool = False) -> dict async classmethod ¶
Initialize all sandbox instances concurrently.
This should be called after launch_all_sandboxes() and after registering any hooks.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sandbox_instances | dict[str, BaseSandbox] | Dict of sandbox_type -> NativeDockerSandbox instance | required |
continue_on_error | bool | If True, continue initializing other sandboxes when one fails, and return a map of sandbox_type -> Exception | None instead of raising. If False, propagate errors. | False |
launch_all_sandboxes(session_id: str, sandbox_configs: dict, shared_volume_id: str = None, scripts_volume_id: str = None, tools_volume_id: str = None) -> dict async classmethod ¶
Launch all sandbox instances as separate Docker containers.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
session_id | str | Session identifier | required |
sandbox_configs | dict | Dictionary of sandbox_type -> ContainerConfig | required |
shared_volume_id | str | Optional shared volume to mount to all sandboxes (unused, configs already updated) | None |
scripts_volume_id | str | Optional scripts volume to mount to all sandboxes (unused, configs already updated) | None |
tools_volume_id | str | Optional tools volume to mount to all sandboxes (unused, configs already updated) | None |
Returns:
| Type | Description |
|---|---|
dict | Dictionary mapping sandbox_type to NativeDockerSandbox instance |
patch_file_func(files_func_to_content: dict[str, str], lang: str = 'c') ¶
Replace a function in a file inside the container with new content.
patch_search_replace(file: str, search: str, replace: str) ¶
Replace all occurrences of 'search' with 'replace' in the specified file.
run_command_in_container(command: str | list[str], timeout: int | None = None) -> tuple[str, int] ¶
Run a command inside the container.
wait_for_ready_or_error() -> bool async ¶
Wait for a specific sandbox to be ready or error.
Neo4jInitializer ¶
Bases: SandboxInitializer
Initializer that initializes Neo4j code analysis capabilities to sandboxes.
async_initialize(all_sandboxes: dict[str, BaseSandbox]) -> None async ¶
Initialize sandbox initializer (async version).
RemoteDockerSandbox ¶
Bases: NativeDockerSandbox
Remote Docker sandbox implementation using Docker API over SSH/TCP.
This backend extends NativeDockerSandbox to support remote Docker daemons, enabling execution on remote machines while maintaining the same interface.
Key differences from NativeDockerSandbox: - Docker client connects to remote daemon (requires docker_host config) - Volume population uses put_archive instead of bind mounts - Network configuration uses remote host IP instead of loopback - Image operations use Docker SDK instead of subprocess - All operations performed via Docker API (no local dependencies)
Configuration
[sandbox] backend = "remotedocker" docker_host = "ssh://user@remote-host" # or tcp://host:2376 docker_remote_host = "192.168.1.100" # optional, auto-parsed if not set
Environment Variables (fallback): DOCKER_HOST: Remote Docker daemon URL DOCKER_REMOTE_HOST: Remote host IP for service connections DOCKER_TLS_CERTDIR: TLS certificate directory for TCP
Usage
export DOCKER_HOST="ssh://user@gpu-server" python -m aigise.evaluations ...
__init__(container_config, session_id: str = None, backend_type: str = None, sandbox_type: str = None) ¶
Initialize remote Docker sandbox.
Overrides parent to use remote Docker client instead of docker.from_env().
async_initialize() -> None async ¶
Initialize the sandbox.
build_image_from_dockerfile(config) -> Optional[DockerBuildResult] classmethod ¶
Build image using Docker SDK (remote-compatible).
cache_sandboxes(sandbox_instances: dict, shared_volume_id: str, cache_dir: str, task_name: str) -> dict classmethod ¶
Cache containers on remote Docker.
can_pull_image(image_name: str) -> bool classmethod ¶
Pull image on remote Docker daemon.
copy_directory_from_container(src_path: str, dst_path: str) ¶
Copy a directory from the container to local filesystem.
copy_directory_to_container(src_path: str, dst_path: str) ¶
Copy a directory from the host to the container.
copy_file_from_container(src_path: str, dst_path: str) ¶
Copy a file from the container to local filesystem.
copy_file_to_container(local_path: str, container_path: str) ¶
Copy a single file to the container.
create_shared_volume(volume_name_prefix: str, init_data_path: Path = None, tools_top_roots: set[str] | None = None) -> tuple[str, str, str] classmethod ¶
Create and initialize three shared volumes.
Creates three volumes: 1. Read-only volume with sandbox scripts (mapped to /sandbox_scripts) 2. Read-write volume with user data (mapped to /shared) 3. Read-write volume with bash tools (mapped to /bash_tools)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
volume_name_prefix | str | Prefix for volume names (e.g., session_id) | required |
init_data_path | Path | Path to initial data to copy into the rw volume (optional) | None |
tools_top_roots | set[str] | None | Optional set of top-level bash_tools roots to stage. If None, stage all bash tools (built-in + plugins). | None |
Returns:
| Type | Description |
|---|---|
tuple[str, str, str] | Tuple of (scripts_volume_id, data_volume_id, tools_volume_id) |
create_single_sandbox(session_id: str, sandbox_type: str, container_config) -> tuple[str, NativeDockerSandbox] async classmethod ¶
Create a single sandbox instance without initialization.
This method only creates the Docker container and sandbox instance. Call initialize_all_sandboxes() afterwards to initialize.
create_tar_bytes(file_content: str, arcname: str) -> bytes ¶
Pack the given file content into a tar archive.
delete_container(max_wait: int = 10) ¶
Delete the container.
delete_shared_volumes(scripts_volume_id: str = None, data_volume_id: str = None, tools_volume_id: str = None) -> None classmethod ¶
Delete shared volumes using Docker API.
ensure_docker_image(config) -> tuple[bool, Optional[str]] classmethod ¶
Ensure image is available on remote daemon.
ensure_ready() -> None async ¶
Ensure the sandbox is ready.
extract_file_from_container(filepath: str) -> str ¶
Extract the content of the specified file from the container.
extract_file_from_container_bytes(filepath: str) -> bytes ¶
Extract the content of the specified file from the container as bytes.
get_file_content(filepath: str) -> str ¶
Retrieve the content of a file inside the container.
get_function_content(key: str, lang: str = 'c', line_in_func: int = -1) -> tuple[str, int, int] ¶
Retrieve the content of a specific function from a file inside the container.
get_work_dir() -> str ¶
Get the working directory of the container.
image_exists_locally(image_name: str) -> bool classmethod ¶
Check if image exists on remote Docker daemon.
initialize_all_sandboxes(sandbox_instances: dict[str, BaseSandbox], *, continue_on_error: bool = False) -> dict async classmethod ¶
Initialize all sandbox instances concurrently.
This should be called after launch_all_sandboxes() and after registering any hooks.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sandbox_instances | dict[str, BaseSandbox] | Dict of sandbox_type -> NativeDockerSandbox instance | required |
continue_on_error | bool | If True, continue initializing other sandboxes when one fails, and return a map of sandbox_type -> Exception | None instead of raising. If False, propagate errors. | False |
launch_all_sandboxes(session_id: str, sandbox_configs: dict, shared_volume_id: str = None, scripts_volume_id: str = None, tools_volume_id: str = None) -> dict async classmethod ¶
Launch all sandbox instances on remote Docker daemon.
patch_file_func(files_func_to_content: dict[str, str], lang: str = 'c') ¶
Replace a function in a file inside the container with new content.
patch_search_replace(file: str, search: str, replace: str) ¶
Replace all occurrences of 'search' with 'replace' in the specified file.
run_command_in_container(command: str | list[str], timeout: int | None = None) -> tuple[str, int] ¶
Run a command inside the container.
set_config(config) -> None classmethod ¶
Inject config into the backend class.
Called by factory before backend methods are invoked.
wait_for_ready_or_error() -> bool async ¶
Wait for a specific sandbox to be ready or error.
SandboxInitializer ¶
Bases: ABC
Base class for sandbox functionality initializers.
async_initialize(all_sandboxes: dict[str, BaseSandbox]) -> None async ¶
Initialize sandbox initializer (async version).
create_sandbox_class(backend_class: Type[BaseSandbox], initializer_class: Type) -> Type[BaseSandbox] ¶
Create a sandbox class by combining a backend with a initializer.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
backend_class | Type[BaseSandbox] | The backend sandbox class (e.g., NativeDockerSandbox) | required |
initializer_class | Type | Initializer class to add functionality | required |
Returns:
| Type | Description |
|---|---|
Type[BaseSandbox] | A new class that combines the backend and initializer |
get_backend_class(backend_type: str, config=None) -> Type[BaseSandbox] ¶
Get the backend class for a given backend type.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
backend_type | str | The type of backend needed (e.g., 'native', 'k8s') | required |
config | Optional config to inject into backend (for remotedocker) | None |
Returns:
| Type | Description |
|---|---|
Type[BaseSandbox] | The backend class |
Raises:
| Type | Description |
|---|---|
ValueError | If backend type is not supported |
get_initializer_class(sandbox_type: str) -> Type ¶
Get the initializer class for a given sandbox type.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sandbox_type | str | The type of sandbox functionality needed | required |
Returns:
| Type | Description |
|---|---|
Type | The initializer class, or the base SandboxInitializer if not found |
aigise.sandbox.native_docker_sandbox ¶
logger = logging.getLogger(__name__) module-attribute ¶
BaseSandbox ¶
Bases: ABC
Base class for all sandbox implementations.
async_initialize() -> None async ¶
Initialize the sandbox.
cache_sandboxes(sandbox_instances: dict, shared_volume_id: str, cache_dir: str, task_name: str) -> dict abstractmethod classmethod ¶
Cache sandbox states and shared volume content.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sandbox_instances | dict | Dictionary mapping sandbox types to sandbox instances | required |
shared_volume_id | str | Shared volume identifier to backup | required |
cache_dir | str | Directory to store cache files | required |
task_name | str | Task name for cache naming | required |
Returns:
| Type | Description |
|---|---|
dict | Dictionary with cache results including backup paths and cached images |
copy_file_from_container(src_path: str, dst_path: str) abstractmethod ¶
Copy a file from the container to local filesystem.
copy_file_to_container(local_path: str, container_path: str) abstractmethod ¶
Copy a file from local filesystem to the container.
create_shared_volume(volume_name_prefix: str, init_data_path: Path = None, tools_top_roots: set[str] | None = None) -> tuple[str, str, str] abstractmethod classmethod ¶
Create and initialize three shared volumes.
Creates three volumes: 1. Read-only volume with sandbox scripts (mapped to /sandbox_scripts) 2. Read-write volume with user data (mapped to /shared) 3. Read-write volume with bash tools (mapped to /bash_tools)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
volume_name_prefix | str | Prefix for volume names (e.g., session_id) | required |
init_data_path | Path | Path to initial data to copy into the rw volume (optional) | None |
tools_top_roots | set[str] | None | Optional set of top-level bash_tools roots to stage. If None, stage all bash tools. | None |
Returns:
| Type | Description |
|---|---|
tuple[str, str, str] | Tuple of (scripts_volume_id, data_volume_id, tools_volume_id) |
create_single_sandbox(session_id: str, sandbox_type: str, container_config) -> Exception abstractmethod async classmethod ¶
Create a single sandbox instance asynchronously.
delete_shared_volumes(scripts_volume_id: str = None, data_volume_id: str = None, tools_volume_id: str = None) -> None abstractmethod classmethod ¶
Delete shared volumes.
ensure_ready() -> None async ¶
Ensure the sandbox is ready.
extract_file_from_container(filepath: str) -> str abstractmethod ¶
Extract file content from the container.
extract_file_from_container_bytes(filepath: str) -> bytes abstractmethod ¶
Extract file content from the container.
get_work_dir() abstractmethod ¶
Get the current working directory in the container.
launch_all_sandboxes(session_id: str, sandbox_configs: dict, shared_volume_id: str = None, scripts_volume_id: str = None, tools_volume_id: str = None) -> dict abstractmethod async classmethod ¶
Launch all sandbox instances for a session.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
session_id | str | Session identifier | required |
sandbox_configs | dict | Dictionary of sandbox_type -> ContainerConfig | required |
shared_volume_id | str | Optional shared volume to mount to all sandboxes | None |
scripts_volume_id | str | Optional scripts volume to mount to all sandboxes | None |
tools_volume_id | str | Optional tools volume to mount to all sandboxes | None |
Returns: Dictionary mapping sandbox_type to sandbox instance or connection info
run_command_in_container(command: str | list[str], timeout: int | None = None) -> tuple[str, int] abstractmethod ¶
Run a command inside the container.
wait_for_ready_or_error() -> bool async ¶
Wait for a specific sandbox to be ready or error.
ContainerConfig dataclass ¶
Lightweight config for Docker-backed sandboxes.
This is an internal convenience type to keep sandbox code tidy and typed. It intentionally mirrors common docker SDK/run options that we may support. Any unsupported fields can be kept in extra for forward-compat.
DockerBuildResult dataclass ¶
Result of a Docker image build operation.
NativeDockerSandbox ¶
Bases: BaseSandbox
Native Docker sandbox implementation using direct Docker API.
__init__(container_config: ContainerConfig, session_id: str = None, backend_type: str = None, sandbox_type: str = None) ¶
Initialize NativeDockerSandbox.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
container_config | ContainerConfig | ContainerConfig options controlling container launch (must include image or container_id) | required |
async_initialize() -> None async ¶
Initialize the sandbox.
cache_sandboxes(sandbox_instances: dict, shared_volume_id: str, cache_dir: str, task_name: str) -> dict classmethod ¶
Cache Docker containers and shared volume content.
This method will: 1. Backup shared volume content to a tar.gz file 2. Commit each running container to a new image
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
session_id | Session identifier | required | |
sandbox_instances | dict | Dictionary mapping sandbox types to NativeDockerSandbox instances | required |
shared_volume_id | str | Docker volume name to backup | required |
cache_dir | str | Directory to store cache files | required |
task_name | str | Task name for naming cached resources | required |
Returns:
| Type | Description |
|---|---|
dict | Dictionary with cache results |
copy_directory_from_container(src_path: str, dst_path: str) ¶
Copy a directory from the container to local filesystem.
copy_directory_to_container(src_path: str, dst_path: str) ¶
Copy a directory from the host to the container.
copy_file_from_container(src_path: str, dst_path: str) ¶
Copy a file from the container to local filesystem.
copy_file_to_container(local_path: str, container_path: str) ¶
Copy a single file to the container.
create_shared_volume(volume_name_prefix: str, init_data_path: Path = None, tools_top_roots: set[str] | None = None) -> tuple[str, str, str] classmethod ¶
Create and initialize three shared volumes.
Creates three volumes: 1. Read-only volume with sandbox scripts (mapped to /sandbox_scripts) 2. Read-write volume with user data (mapped to /shared) 3. Read-write volume with bash tools (mapped to /bash_tools)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
volume_name_prefix | str | Prefix for volume names (e.g., session_id) | required |
init_data_path | Path | Path to initial data to copy into the rw volume (optional) | None |
tools_top_roots | set[str] | None | Optional set of top-level bash_tools roots to stage. If None, stage all bash tools (built-in + plugins). | None |
Returns:
| Type | Description |
|---|---|
tuple[str, str, str] | Tuple of (scripts_volume_id, data_volume_id, tools_volume_id) |
create_single_sandbox(session_id: str, sandbox_type: str, container_config) -> tuple[str, NativeDockerSandbox] async classmethod ¶
Create a single sandbox instance without initialization.
This method only creates the Docker container and sandbox instance. Call initialize_all_sandboxes() afterwards to initialize.
create_tar_bytes(file_content: str, arcname: str) -> bytes ¶
Pack the given file content into a tar archive.
delete_container(max_wait: int = 10) ¶
Delete the container.
delete_shared_volumes(scripts_volume_id: str = None, data_volume_id: str = None, tools_volume_id: str = None) -> None classmethod ¶
Delete shared volumes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scripts_volume_id | str | ID of the scripts volume to delete | None |
data_volume_id | str | ID of the data volume to delete | None |
tools_volume_id | str | ID of the tools volume to delete | None |
ensure_ready() -> None async ¶
Ensure the sandbox is ready.
extract_file_from_container(filepath: str) -> str ¶
Extract the content of the specified file from the container.
extract_file_from_container_bytes(filepath: str) -> bytes ¶
Extract the content of the specified file from the container as bytes.
get_file_content(filepath: str) -> str ¶
Retrieve the content of a file inside the container.
get_function_content(key: str, lang: str = 'c', line_in_func: int = -1) -> tuple[str, int, int] ¶
Retrieve the content of a specific function from a file inside the container.
get_work_dir() -> str ¶
Get the working directory of the container.
initialize_all_sandboxes(sandbox_instances: dict[str, BaseSandbox], *, continue_on_error: bool = False) -> dict async classmethod ¶
Initialize all sandbox instances concurrently.
This should be called after launch_all_sandboxes() and after registering any hooks.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sandbox_instances | dict[str, BaseSandbox] | Dict of sandbox_type -> NativeDockerSandbox instance | required |
continue_on_error | bool | If True, continue initializing other sandboxes when one fails, and return a map of sandbox_type -> Exception | None instead of raising. If False, propagate errors. | False |
launch_all_sandboxes(session_id: str, sandbox_configs: dict, shared_volume_id: str = None, scripts_volume_id: str = None, tools_volume_id: str = None) -> dict async classmethod ¶
Launch all sandbox instances as separate Docker containers.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
session_id | str | Session identifier | required |
sandbox_configs | dict | Dictionary of sandbox_type -> ContainerConfig | required |
shared_volume_id | str | Optional shared volume to mount to all sandboxes (unused, configs already updated) | None |
scripts_volume_id | str | Optional scripts volume to mount to all sandboxes (unused, configs already updated) | None |
tools_volume_id | str | Optional tools volume to mount to all sandboxes (unused, configs already updated) | None |
Returns:
| Type | Description |
|---|---|
dict | Dictionary mapping sandbox_type to NativeDockerSandbox instance |
patch_file_func(files_func_to_content: dict[str, str], lang: str = 'c') ¶
Replace a function in a file inside the container with new content.
patch_search_replace(file: str, search: str, replace: str) ¶
Replace all occurrences of 'search' with 'replace' in the specified file.
run_command_in_container(command: str | list[str], timeout: int | None = None) -> tuple[str, int] ¶
Run a command inside the container.
wait_for_ready_or_error() -> bool async ¶
Wait for a specific sandbox to be ready or error.
SandboxState ¶
Bases: Enum
Sandbox initialization states.
build_image_from_dockerfile(config: ContainerConfig) -> DockerBuildResult ¶
Build Docker image from a direct Dockerfile.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dockerfile_path | Path to the Dockerfile | required | |
image_name | Name and tag for the built image (e.g., 'myapp:latest') | required | |
build_context | Directory to use as build context. If None, uses dockerfile directory | required | |
build_args | Build-time variables for Docker build (--build-arg) | required |
Returns:
| Type | Description |
|---|---|
DockerBuildResult | DockerBuildResult with build status and details |
can_pull_image(image_name: str) -> bool ¶
Try to pull Docker image and return success status.
ensure_docker_image(config: ContainerConfig) -> tuple[bool, Optional[str]] ¶
Ensure Docker image is available, using dockerfile fallback if needed.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config | ContainerConfig | ContainerConfig with image name and optional dockerfile config | required |
Returns:
| Type | Description |
|---|---|
tuple[bool, Optional[str]] | Tuple of (success, error_message). If success is False, error_message explains why. |
image_exists_locally(image_name: str) -> bool ¶
Check if Docker image exists locally.
aigise.sandbox.remote_docker_sandbox ¶
Remote Docker Sandbox implementation.
This module provides a sandbox backend that connects to remote Docker daemons via SSH or TCP, enabling distributed execution across multiple machines.
logger = logging.getLogger(__name__) module-attribute ¶
DockerBuildResult dataclass ¶
Result of a Docker image build operation.
NativeDockerSandbox ¶
Bases: BaseSandbox
Native Docker sandbox implementation using direct Docker API.
__init__(container_config: ContainerConfig, session_id: str = None, backend_type: str = None, sandbox_type: str = None) ¶
Initialize NativeDockerSandbox.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
container_config | ContainerConfig | ContainerConfig options controlling container launch (must include image or container_id) | required |
async_initialize() -> None async ¶
Initialize the sandbox.
cache_sandboxes(sandbox_instances: dict, shared_volume_id: str, cache_dir: str, task_name: str) -> dict classmethod ¶
Cache Docker containers and shared volume content.
This method will: 1. Backup shared volume content to a tar.gz file 2. Commit each running container to a new image
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
session_id | Session identifier | required | |
sandbox_instances | dict | Dictionary mapping sandbox types to NativeDockerSandbox instances | required |
shared_volume_id | str | Docker volume name to backup | required |
cache_dir | str | Directory to store cache files | required |
task_name | str | Task name for naming cached resources | required |
Returns:
| Type | Description |
|---|---|
dict | Dictionary with cache results |
copy_directory_from_container(src_path: str, dst_path: str) ¶
Copy a directory from the container to local filesystem.
copy_directory_to_container(src_path: str, dst_path: str) ¶
Copy a directory from the host to the container.
copy_file_from_container(src_path: str, dst_path: str) ¶
Copy a file from the container to local filesystem.
copy_file_to_container(local_path: str, container_path: str) ¶
Copy a single file to the container.
create_shared_volume(volume_name_prefix: str, init_data_path: Path = None, tools_top_roots: set[str] | None = None) -> tuple[str, str, str] classmethod ¶
Create and initialize three shared volumes.
Creates three volumes: 1. Read-only volume with sandbox scripts (mapped to /sandbox_scripts) 2. Read-write volume with user data (mapped to /shared) 3. Read-write volume with bash tools (mapped to /bash_tools)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
volume_name_prefix | str | Prefix for volume names (e.g., session_id) | required |
init_data_path | Path | Path to initial data to copy into the rw volume (optional) | None |
tools_top_roots | set[str] | None | Optional set of top-level bash_tools roots to stage. If None, stage all bash tools (built-in + plugins). | None |
Returns:
| Type | Description |
|---|---|
tuple[str, str, str] | Tuple of (scripts_volume_id, data_volume_id, tools_volume_id) |
create_single_sandbox(session_id: str, sandbox_type: str, container_config) -> tuple[str, NativeDockerSandbox] async classmethod ¶
Create a single sandbox instance without initialization.
This method only creates the Docker container and sandbox instance. Call initialize_all_sandboxes() afterwards to initialize.
create_tar_bytes(file_content: str, arcname: str) -> bytes ¶
Pack the given file content into a tar archive.
delete_container(max_wait: int = 10) ¶
Delete the container.
delete_shared_volumes(scripts_volume_id: str = None, data_volume_id: str = None, tools_volume_id: str = None) -> None classmethod ¶
Delete shared volumes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scripts_volume_id | str | ID of the scripts volume to delete | None |
data_volume_id | str | ID of the data volume to delete | None |
tools_volume_id | str | ID of the tools volume to delete | None |
ensure_ready() -> None async ¶
Ensure the sandbox is ready.
extract_file_from_container(filepath: str) -> str ¶
Extract the content of the specified file from the container.
extract_file_from_container_bytes(filepath: str) -> bytes ¶
Extract the content of the specified file from the container as bytes.
get_file_content(filepath: str) -> str ¶
Retrieve the content of a file inside the container.
get_function_content(key: str, lang: str = 'c', line_in_func: int = -1) -> tuple[str, int, int] ¶
Retrieve the content of a specific function from a file inside the container.
get_work_dir() -> str ¶
Get the working directory of the container.
initialize_all_sandboxes(sandbox_instances: dict[str, BaseSandbox], *, continue_on_error: bool = False) -> dict async classmethod ¶
Initialize all sandbox instances concurrently.
This should be called after launch_all_sandboxes() and after registering any hooks.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sandbox_instances | dict[str, BaseSandbox] | Dict of sandbox_type -> NativeDockerSandbox instance | required |
continue_on_error | bool | If True, continue initializing other sandboxes when one fails, and return a map of sandbox_type -> Exception | None instead of raising. If False, propagate errors. | False |
launch_all_sandboxes(session_id: str, sandbox_configs: dict, shared_volume_id: str = None, scripts_volume_id: str = None, tools_volume_id: str = None) -> dict async classmethod ¶
Launch all sandbox instances as separate Docker containers.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
session_id | str | Session identifier | required |
sandbox_configs | dict | Dictionary of sandbox_type -> ContainerConfig | required |
shared_volume_id | str | Optional shared volume to mount to all sandboxes (unused, configs already updated) | None |
scripts_volume_id | str | Optional scripts volume to mount to all sandboxes (unused, configs already updated) | None |
tools_volume_id | str | Optional tools volume to mount to all sandboxes (unused, configs already updated) | None |
Returns:
| Type | Description |
|---|---|
dict | Dictionary mapping sandbox_type to NativeDockerSandbox instance |
patch_file_func(files_func_to_content: dict[str, str], lang: str = 'c') ¶
Replace a function in a file inside the container with new content.
patch_search_replace(file: str, search: str, replace: str) ¶
Replace all occurrences of 'search' with 'replace' in the specified file.
run_command_in_container(command: str | list[str], timeout: int | None = None) -> tuple[str, int] ¶
Run a command inside the container.
wait_for_ready_or_error() -> bool async ¶
Wait for a specific sandbox to be ready or error.
RemoteDockerSandbox ¶
Bases: NativeDockerSandbox
Remote Docker sandbox implementation using Docker API over SSH/TCP.
This backend extends NativeDockerSandbox to support remote Docker daemons, enabling execution on remote machines while maintaining the same interface.
Key differences from NativeDockerSandbox: - Docker client connects to remote daemon (requires docker_host config) - Volume population uses put_archive instead of bind mounts - Network configuration uses remote host IP instead of loopback - Image operations use Docker SDK instead of subprocess - All operations performed via Docker API (no local dependencies)
Configuration
[sandbox] backend = "remotedocker" docker_host = "ssh://user@remote-host" # or tcp://host:2376 docker_remote_host = "192.168.1.100" # optional, auto-parsed if not set
Environment Variables (fallback): DOCKER_HOST: Remote Docker daemon URL DOCKER_REMOTE_HOST: Remote host IP for service connections DOCKER_TLS_CERTDIR: TLS certificate directory for TCP
Usage
export DOCKER_HOST="ssh://user@gpu-server" python -m aigise.evaluations ...
__init__(container_config, session_id: str = None, backend_type: str = None, sandbox_type: str = None) ¶
Initialize remote Docker sandbox.
Overrides parent to use remote Docker client instead of docker.from_env().
async_initialize() -> None async ¶
Initialize the sandbox.
build_image_from_dockerfile(config) -> Optional[DockerBuildResult] classmethod ¶
Build image using Docker SDK (remote-compatible).
cache_sandboxes(sandbox_instances: dict, shared_volume_id: str, cache_dir: str, task_name: str) -> dict classmethod ¶
Cache containers on remote Docker.
can_pull_image(image_name: str) -> bool classmethod ¶
Pull image on remote Docker daemon.
copy_directory_from_container(src_path: str, dst_path: str) ¶
Copy a directory from the container to local filesystem.
copy_directory_to_container(src_path: str, dst_path: str) ¶
Copy a directory from the host to the container.
copy_file_from_container(src_path: str, dst_path: str) ¶
Copy a file from the container to local filesystem.
copy_file_to_container(local_path: str, container_path: str) ¶
Copy a single file to the container.
create_shared_volume(volume_name_prefix: str, init_data_path: Path = None, tools_top_roots: set[str] | None = None) -> tuple[str, str, str] classmethod ¶
Create and initialize three shared volumes.
Creates three volumes: 1. Read-only volume with sandbox scripts (mapped to /sandbox_scripts) 2. Read-write volume with user data (mapped to /shared) 3. Read-write volume with bash tools (mapped to /bash_tools)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
volume_name_prefix | str | Prefix for volume names (e.g., session_id) | required |
init_data_path | Path | Path to initial data to copy into the rw volume (optional) | None |
tools_top_roots | set[str] | None | Optional set of top-level bash_tools roots to stage. If None, stage all bash tools (built-in + plugins). | None |
Returns:
| Type | Description |
|---|---|
tuple[str, str, str] | Tuple of (scripts_volume_id, data_volume_id, tools_volume_id) |
create_single_sandbox(session_id: str, sandbox_type: str, container_config) -> tuple[str, NativeDockerSandbox] async classmethod ¶
Create a single sandbox instance without initialization.
This method only creates the Docker container and sandbox instance. Call initialize_all_sandboxes() afterwards to initialize.
create_tar_bytes(file_content: str, arcname: str) -> bytes ¶
Pack the given file content into a tar archive.
delete_container(max_wait: int = 10) ¶
Delete the container.
delete_shared_volumes(scripts_volume_id: str = None, data_volume_id: str = None, tools_volume_id: str = None) -> None classmethod ¶
Delete shared volumes using Docker API.
ensure_docker_image(config) -> tuple[bool, Optional[str]] classmethod ¶
Ensure image is available on remote daemon.
ensure_ready() -> None async ¶
Ensure the sandbox is ready.
extract_file_from_container(filepath: str) -> str ¶
Extract the content of the specified file from the container.
extract_file_from_container_bytes(filepath: str) -> bytes ¶
Extract the content of the specified file from the container as bytes.
get_file_content(filepath: str) -> str ¶
Retrieve the content of a file inside the container.
get_function_content(key: str, lang: str = 'c', line_in_func: int = -1) -> tuple[str, int, int] ¶
Retrieve the content of a specific function from a file inside the container.
get_work_dir() -> str ¶
Get the working directory of the container.
image_exists_locally(image_name: str) -> bool classmethod ¶
Check if image exists on remote Docker daemon.
initialize_all_sandboxes(sandbox_instances: dict[str, BaseSandbox], *, continue_on_error: bool = False) -> dict async classmethod ¶
Initialize all sandbox instances concurrently.
This should be called after launch_all_sandboxes() and after registering any hooks.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sandbox_instances | dict[str, BaseSandbox] | Dict of sandbox_type -> NativeDockerSandbox instance | required |
continue_on_error | bool | If True, continue initializing other sandboxes when one fails, and return a map of sandbox_type -> Exception | None instead of raising. If False, propagate errors. | False |
launch_all_sandboxes(session_id: str, sandbox_configs: dict, shared_volume_id: str = None, scripts_volume_id: str = None, tools_volume_id: str = None) -> dict async classmethod ¶
Launch all sandbox instances on remote Docker daemon.
patch_file_func(files_func_to_content: dict[str, str], lang: str = 'c') ¶
Replace a function in a file inside the container with new content.
patch_search_replace(file: str, search: str, replace: str) ¶
Replace all occurrences of 'search' with 'replace' in the specified file.
run_command_in_container(command: str | list[str], timeout: int | None = None) -> tuple[str, int] ¶
Run a command inside the container.
set_config(config) -> None classmethod ¶
Inject config into the backend class.
Called by factory before backend methods are invoked.
wait_for_ready_or_error() -> bool async ¶
Wait for a specific sandbox to be ready or error.
aigise.sandbox.k8s_sandbox ¶
K8s sandbox implementation using kubectl and K8s Python client.
logger = logging.getLogger(__name__) module-attribute ¶
BaseSandbox ¶
Bases: ABC
Base class for all sandbox implementations.
async_initialize() -> None async ¶
Initialize the sandbox.
cache_sandboxes(sandbox_instances: dict, shared_volume_id: str, cache_dir: str, task_name: str) -> dict abstractmethod classmethod ¶
Cache sandbox states and shared volume content.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sandbox_instances | dict | Dictionary mapping sandbox types to sandbox instances | required |
shared_volume_id | str | Shared volume identifier to backup | required |
cache_dir | str | Directory to store cache files | required |
task_name | str | Task name for cache naming | required |
Returns:
| Type | Description |
|---|---|
dict | Dictionary with cache results including backup paths and cached images |
copy_file_from_container(src_path: str, dst_path: str) abstractmethod ¶
Copy a file from the container to local filesystem.
copy_file_to_container(local_path: str, container_path: str) abstractmethod ¶
Copy a file from local filesystem to the container.
create_shared_volume(volume_name_prefix: str, init_data_path: Path = None, tools_top_roots: set[str] | None = None) -> tuple[str, str, str] abstractmethod classmethod ¶
Create and initialize three shared volumes.
Creates three volumes: 1. Read-only volume with sandbox scripts (mapped to /sandbox_scripts) 2. Read-write volume with user data (mapped to /shared) 3. Read-write volume with bash tools (mapped to /bash_tools)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
volume_name_prefix | str | Prefix for volume names (e.g., session_id) | required |
init_data_path | Path | Path to initial data to copy into the rw volume (optional) | None |
tools_top_roots | set[str] | None | Optional set of top-level bash_tools roots to stage. If None, stage all bash tools. | None |
Returns:
| Type | Description |
|---|---|
tuple[str, str, str] | Tuple of (scripts_volume_id, data_volume_id, tools_volume_id) |
create_single_sandbox(session_id: str, sandbox_type: str, container_config) -> Exception abstractmethod async classmethod ¶
Create a single sandbox instance asynchronously.
delete_shared_volumes(scripts_volume_id: str = None, data_volume_id: str = None, tools_volume_id: str = None) -> None abstractmethod classmethod ¶
Delete shared volumes.
ensure_ready() -> None async ¶
Ensure the sandbox is ready.
extract_file_from_container(filepath: str) -> str abstractmethod ¶
Extract file content from the container.
extract_file_from_container_bytes(filepath: str) -> bytes abstractmethod ¶
Extract file content from the container.
get_work_dir() abstractmethod ¶
Get the current working directory in the container.
launch_all_sandboxes(session_id: str, sandbox_configs: dict, shared_volume_id: str = None, scripts_volume_id: str = None, tools_volume_id: str = None) -> dict abstractmethod async classmethod ¶
Launch all sandbox instances for a session.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
session_id | str | Session identifier | required |
sandbox_configs | dict | Dictionary of sandbox_type -> ContainerConfig | required |
shared_volume_id | str | Optional shared volume to mount to all sandboxes | None |
scripts_volume_id | str | Optional scripts volume to mount to all sandboxes | None |
tools_volume_id | str | Optional tools volume to mount to all sandboxes | None |
Returns: Dictionary mapping sandbox_type to sandbox instance or connection info
run_command_in_container(command: str | list[str], timeout: int | None = None) -> tuple[str, int] abstractmethod ¶
Run a command inside the container.
wait_for_ready_or_error() -> bool async ¶
Wait for a specific sandbox to be ready or error.
ContainerConfig dataclass ¶
Lightweight config for Docker-backed sandboxes.
This is an internal convenience type to keep sandbox code tidy and typed. It intentionally mirrors common docker SDK/run options that we may support. Any unsupported fields can be kept in extra for forward-compat.
K8sSandbox ¶
Bases: BaseSandbox
K8s sandbox representing a specific container within a Pod.
__init__(container_config: ContainerConfig, session_id: str = None, backend_type: str = None, sandbox_type: str = None, pod_name: str = None, container_name: str = None) ¶
Initialize K8sSandbox.
async_initialize() -> None async ¶
Initialize the sandbox.
create_shared_volume(volume_name_prefix: str, init_data_path: Path = None, tools_top_roots: set[str] | None = None) -> tuple[str, str, str] classmethod ¶
Create and initialize three shared PVCs.
Creates three PVCs: 1. Read-only PVC with sandbox scripts (mapped to /sandbox_scripts) 2. Read-write PVC with user data (mapped to /shared) 3. Read-write PVC with bash tools (mapped to /bash_tools)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
volume_name_prefix | str | Prefix for PVC names (e.g., session_id) | required |
init_data_path | Path | Path to initial data to copy into the rw PVC (optional) | None |
tools_top_roots | set[str] | None | Optional set of top-level bash_tools roots to stage. If None, stage all bash tools (built-in + plugins). | None |
Returns:
| Type | Description |
|---|---|
tuple[str, str, str] | Tuple of (scripts_pvc_name, data_pvc_name, tools_pvc_name) |
delete_shared_volumes(scripts_volume_id: str = None, data_volume_id: str = None, tools_volume_id: str = None) -> None classmethod ¶
Delete shared PVCs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scripts_volume_id | str | ID of the scripts PVC to delete (with or without pvc/ prefix) | None |
data_volume_id | str | ID of the data PVC to delete (with or without pvc/ prefix) | None |
tools_volume_id | str | ID of the tools PVC to delete (with or without pvc/ prefix) | None |
ensure_ready() -> None async ¶
Ensure the sandbox is ready.
initialize_all_sandboxes(sandbox_instances: dict, *, continue_on_error: bool = False) -> dict async classmethod ¶
Initialize all sandbox instances concurrently.
This should be called after launch_all_sandboxes() and after registering any hooks.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sandbox_instances | dict | Dict of sandbox_type -> K8sSandbox instance | required |
continue_on_error | bool | If True, continue on failures and return a map of sandbox_type -> Exception | None. If False, propagate errors. | False |
wait_for_ready_or_error() -> bool async ¶
Wait for a specific sandbox to be ready or error.
SandboxState ¶
Bases: Enum
Sandbox initialization states.