Secure, Fast, and Extensible Sandbox runtime for AI agents.
#
# Copyright 2025 The OpenSandbox Authors
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
"""
Synchronous SandboxManager implementation.
"""
import logging
from datetime import datetime, timedelta, timezone
from typing import Any
from opensandbox.config.connection_sync import ConnectionConfigSync
from opensandbox.models.diagnostics import DiagnosticContent, DiagnosticContext
from opensandbox.models.sandboxes import (
CreateSnapshotRequest,
PagedSandboxInfos,
PagedSnapshotInfos,
SandboxFilter,
SandboxInfo,
SandboxRenewResponse,
SnapshotFilter,
SnapshotInfo,
)
from opensandbox.models.templates import (
CreateTemplateRequest,
PagedTemplateInfos,
TemplateFilter,
TemplateInfo,
)
from opensandbox.sync.adapters.factory import AdapterFactorySync
from opensandbox.sync.services.diagnostics import DiagnosticsSync
from opensandbox.sync.services.sandbox import SandboxesSync
logger = logging.getLogger(__name__)
class SandboxManagerSync:
"""
Synchronous sandbox management interface for administrative operations.
This class mirrors the async :class:`opensandbox.manager.SandboxManager`, but all
operations are **blocking** and executed in the current thread.
It is designed for *fleet* / admin workflows (listing, filtering, controlling sandboxes).
For interacting with a single sandbox instance (files/commands/metrics), prefer
:class:`opensandbox.sync.sandbox.SandboxSync`.
Usage Example:
```python
from opensandbox.models.sandboxes import SandboxFilter
from opensandbox.sync.manager import SandboxManagerSync
manager = SandboxManagerSync.create()
infos = manager.list_sandbox_infos(SandboxFilter(states=["RUNNING"]))
manager.close()
```
"""
def __init__(
self,
sandbox_service: SandboxesSync,
connection_config: ConnectionConfigSync,
diagnostics_service: DiagnosticsSync | None = None,
) -> None:
"""
Internal constructor for SandboxManagerSync.
Note: Use :meth:`create` instead.
Args:
sandbox_service: Service for sandbox operations
connection_config: Connection configuration (shared transport, headers, timeouts)
diagnostics_service: Optional service for sandbox diagnostics
"""
self._sandbox_service = sandbox_service
self._connection_config = connection_config
self._diagnostics_service = (
diagnostics_service
or AdapterFactorySync(connection_config).create_diagnostics_service()
)
@property
def connection_config(self) -> ConnectionConfigSync:
"""Provides access to the connection configuration (including shared transport)."""
return self._connection_config
@classmethod
def create(
cls, connection_config: ConnectionConfigSync | None = None
) -> "SandboxManagerSync":
"""
Create a SandboxManagerSync instance with the provided configuration (blocking).
Args:
connection_config: Connection configuration for the manager.
If None, default configuration will be used.
Returns:
Configured sandbox manager instance
"""
config = (
connection_config or ConnectionConfigSync()
).with_transport_if_missing()
factory = AdapterFactorySync(config)
sandbox_service = factory.create_sandbox_service()
diagnostics_service = factory.create_diagnostics_service()
return cls(sandbox_service, config, diagnostics_service)
def list_sandbox_infos(self, filter: SandboxFilter) -> PagedSandboxInfos:
"""
List sandboxes with filtering options.
Args:
filter: Filter criteria for sandbox listing
Returns:
Paged sandbox information matching the filter criteria
Raises:
SandboxException: if the operation fails
"""
return self._sandbox_service.list_sandboxes(filter)
def get_sandbox_info(self, sandbox_id: str) -> SandboxInfo:
"""
Get information for a single sandbox by its ID.
Args:
sandbox_id: Sandbox ID to retrieve information for
Returns:
SandboxInfo for the specified sandbox
Raises:
SandboxException: if the operation fails
"""
logger.debug(f"Getting info for sandbox: {sandbox_id}")
return self._sandbox_service.get_sandbox_info(sandbox_id)
def get_diagnostic_context(self, sandbox_id: str) -> DiagnosticContext:
"""Get backend routing context without connecting to execd."""
return self._diagnostics_service.get_context(sandbox_id)
def get_diagnostic_logs(
self,
sandbox_id: str,
scope: str,
) -> DiagnosticContent:
"""
Get diagnostic log content for a sandbox by ID.
Args:
sandbox_id: Sandbox ID to retrieve diagnostics for
scope: Required diagnostic scope such as "container", "lifecycle", or "all".
"""
return self._diagnostics_service.get_logs(sandbox_id, scope)
def get_diagnostic_events(
self,
sandbox_id: str,
scope: str,
) -> DiagnosticContent:
"""
Get diagnostic event content for a sandbox by ID.
Args:
sandbox_id: Sandbox ID to retrieve diagnostics for
scope: Required diagnostic scope such as "runtime", "lifecycle", or "all".
"""
return self._diagnostics_service.get_events(sandbox_id, scope)
def patch_sandbox_metadata(
self, sandbox_id: str, patch: dict[str, str | None]
) -> SandboxInfo:
"""
Patch metadata for a sandbox.
String values add or replace keys; None deletes keys.
"""
logger.info(f"Patching metadata for sandbox: {sandbox_id}")
return self._sandbox_service.patch_sandbox_metadata(sandbox_id, patch)
def kill_sandbox(self, sandbox_id: str) -> None:
"""
Request irreversible termination of the remote sandbox. Returns when
deletion is accepted; runtime cleanup may continue afterward.
Args:
sandbox_id: Sandbox ID to terminate
Raises:
SandboxException: if the operation fails
"""
logger.info(f"Terminating sandbox: {sandbox_id}")
self._sandbox_service.kill_sandbox(sandbox_id)
logger.info(f"Sandbox deletion accepted: {sandbox_id}")
def renew_sandbox(
self, sandbox_id: str, timeout: timedelta
) -> SandboxRenewResponse:
"""
Renew expiration time for a single sandbox.
The new expiration time will be set to the current time plus the provided duration.
Args:
sandbox_id: Sandbox ID to renew
timeout: Duration to add to the current time to set the new expiration
Raises:
SandboxException: if the operation fails
"""
# Use timezone-aware UTC datetime to avoid cross-timezone ambiguity.
new_expiration = datetime.now(timezone.utc) + timeout
logger.info(f"Renew expiration for sandbox {sandbox_id} to {new_expiration}")
return self._sandbox_service.renew_sandbox_expiration(
sandbox_id, new_expiration
)
def pause_sandbox(self, sandbox_id: str) -> None:
"""
Pause a single sandbox while preserving its state.
Args:
sandbox_id: Sandbox ID to pause
Raises:
SandboxException: if the operation fails
"""
logger.info(f"Pausing sandbox: {sandbox_id}")
self._sandbox_service.pause_sandbox(sandbox_id)
def resume_sandbox(self, sandbox_id: str) -> None:
"""
Resume a previously paused sandbox.
Args:
sandbox_id: Sandbox ID to resume
Raises:
SandboxException: if the operation fails
"""
logger.info(f"Resuming sandbox: {sandbox_id}")
self._sandbox_service.resume_sandbox(sandbox_id)
def create_snapshot(self, sandbox_id: str, name: str | None = None) -> SnapshotInfo:
"""Create a snapshot from a sandbox (blocking)."""
return self._sandbox_service.create_snapshot(
sandbox_id, CreateSnapshotRequest(name=name)
)
def get_snapshot(self, snapshot_id: str) -> SnapshotInfo:
"""Get information for a snapshot by id (blocking)."""
return self._sandbox_service.get_snapshot(snapshot_id)
def list_snapshots(self, filter: SnapshotFilter) -> PagedSnapshotInfos:
"""List snapshots with filtering options (blocking)."""
return self._sandbox_service.list_snapshots(filter)
def delete_snapshot(self, snapshot_id: str) -> None:
"""Delete a snapshot by id (blocking)."""
self._sandbox_service.delete_snapshot(snapshot_id)
def create_template(self, request: CreateTemplateRequest) -> TemplateInfo:
"""Create a fsb template (golden-image build); the build is asynchronous (blocking)."""
return self._sandbox_service.create_template(request)
def get_template(self, template_id: str) -> TemplateInfo:
"""Get a template with its latest build status by id (blocking)."""
return self._sandbox_service.get_template(template_id)
def list_templates(self, filter: TemplateFilter) -> PagedTemplateInfos:
"""List templates with metadata filtering and pagination options (blocking)."""
return self._sandbox_service.list_templates(filter)
def delete_template(self, template_id: str) -> None:
"""Delete a template by id (blocking). Running sandboxes are unaffected."""
self._sandbox_service.delete_template(template_id)
def close(self) -> None:
"""
Close local resources associated with this sandbox manager.
This method closes HTTP client resources and other local resources.
Note: This method logs errors but does not raise exceptions to avoid
issues in context manager cleanup.
"""
try:
self._connection_config.close_transport_if_owned()
except Exception as e:
logger.warning(
f"Error closing resources for sandbox manager: {e}", exc_info=True
)
def __enter__(self) -> "SandboxManagerSync":
"""Sync context manager entry."""
return self
def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
"""Sync context manager exit."""
self.close()