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 sandbox service adapter implementation.
"""
import logging
from datetime import datetime, timedelta
import httpx
from opensandbox._httpx import build_redirect_client_options
from opensandbox.adapters.converter.exception_converter import (
ExceptionConverter,
)
from opensandbox.adapters.converter.response_handler import (
handle_api_error,
require_parsed,
)
from opensandbox.adapters.converter.sandbox_model_converter import (
SandboxModelConverter,
)
from opensandbox.adapters.converter.template_model_converter import (
TemplateModelConverter,
)
from opensandbox.adapters.sandboxes_adapter import encode_metadata_filter
from opensandbox.api.lifecycle.types import UNSET
from opensandbox.config.connection_sync import ConnectionConfigSync
from opensandbox.internal.readiness import constrain_readiness_request
from opensandbox.models.sandboxes import (
CreateSnapshotRequest,
CredentialProxyConfig,
IdlePolicy,
NetworkPolicy,
PagedSandboxInfos,
PagedSnapshotInfos,
PlatformSpec,
SandboxCreateResponse,
SandboxEndpoint,
SandboxFilter,
SandboxImageSpec,
SandboxInfo,
SandboxLifecycle,
SandboxRenewResponse,
SnapshotFilter,
SnapshotInfo,
Volume,
)
from opensandbox.models.templates import (
CreateTemplateRequest,
PagedTemplateInfos,
TemplateFilter,
TemplateInfo,
)
from opensandbox.sync.services.sandbox import SandboxesSync
logger = logging.getLogger(__name__)
class SandboxesAdapterSync(SandboxesSync):
def __init__(self, connection_config: ConnectionConfigSync) -> None:
self.connection_config = connection_config
from opensandbox.adapters.endpoint_cache import EndpointCache
if not connection_config.endpoint_cache_disabled:
self._endpoint_cache: EndpointCache | None = EndpointCache(
maxsize=connection_config.endpoint_cache_size or 1024,
ttl=connection_config.endpoint_cache_ttl.total_seconds(),
)
else:
self._endpoint_cache = None
from opensandbox.api.lifecycle import AuthenticatedClient
api_key = self.connection_config.get_api_key()
timeout_seconds = self.connection_config.request_timeout.total_seconds()
timeout = httpx.Timeout(timeout_seconds)
headers = {
"User-Agent": self.connection_config.user_agent,
**self.connection_config.headers,
}
if api_key:
headers["OPEN-SANDBOX-API-KEY"] = api_key
self._client = AuthenticatedClient(
base_url=self.connection_config.get_base_url(),
token=api_key or "",
prefix="",
auth_header_name="OPEN-SANDBOX-API-KEY",
timeout=timeout,
follow_redirects=self.connection_config.follow_redirects,
)
self._httpx_client = httpx.Client(
base_url=self.connection_config.get_base_url(),
headers=headers,
timeout=timeout,
transport=self.connection_config.transport,
**build_redirect_client_options(
self.connection_config,
self.connection_config.get_base_url(),
additional_request_hooks=(constrain_readiness_request,),
),
)
self._client.set_httpx_client(self._httpx_client)
def _get_client(self):
return self._client
def create_sandbox(
self,
spec: SandboxImageSpec | None,
entrypoint: list[str] | None,
env: dict[str, str],
metadata: dict[str, str],
timeout: timedelta | None,
resource: dict[str, str],
network_policy: NetworkPolicy | None,
extensions: dict[str, str],
volumes: list[Volume] | None,
platform: PlatformSpec | None = None,
secure_access: bool = False,
snapshot_id: str | None = None,
credential_proxy: CredentialProxyConfig | None = None,
resource_requests: dict[str, str] | None = None,
lifecycle: SandboxLifecycle | None = None,
) -> SandboxCreateResponse:
logger.info(
f"Creating sandbox with startup source: {spec.image if spec is not None else snapshot_id}"
)
try:
from opensandbox.api.lifecycle.api.sandboxes import post_sandboxes
from opensandbox.api.lifecycle.models import (
CreateSandboxResponse as ApiCreateSandboxResponse,
)
create_request = SandboxModelConverter.to_api_create_sandbox_request(
spec=spec,
entrypoint=entrypoint,
env=env,
metadata=metadata,
timeout=timeout,
resource=resource,
platform=platform,
network_policy=network_policy,
credential_proxy=credential_proxy,
extensions=extensions,
volumes=volumes,
secure_access=secure_access,
snapshot_id=snapshot_id,
resource_requests=resource_requests,
lifecycle=lifecycle,
)
response_obj = post_sandboxes.sync_detailed(
client=self._get_client(), body=create_request
)
handle_api_error(response_obj, "Create sandbox")
parsed = require_parsed(
response_obj, ApiCreateSandboxResponse, "Create sandbox"
)
return SandboxModelConverter.to_sandbox_create_response(parsed)
except Exception as e:
logger.warning(
f"Failed to create sandbox with startup source {spec.image if spec is not None else snapshot_id}: {e}"
)
raise ExceptionConverter.to_sandbox_exception(e) from e
def create_sandbox_from_template(
self,
template_id: str,
timeout: timedelta,
metadata: dict[str, str] | None = None,
network_policy: NetworkPolicy | None = None,
extensions: dict[str, str] | None = None,
idle_policy: IdlePolicy | None = None,
) -> SandboxCreateResponse:
try:
from opensandbox.api.lifecycle.api.sandboxes import post_sandboxes
from opensandbox.api.lifecycle.models import (
CreateSandboxResponse as ApiCreateSandboxResponse,
)
create_request = SandboxModelConverter.to_api_create_template_sandbox_request(
template_id=template_id,
timeout=timeout,
metadata=metadata,
network_policy=network_policy,
extensions=extensions,
idle_policy=idle_policy,
)
response_obj = post_sandboxes.sync_detailed(
client=self._get_client(), body=create_request
)
handle_api_error(
response_obj, f"Create sandbox from template {template_id}"
)
parsed = require_parsed(
response_obj, ApiCreateSandboxResponse, "Create sandbox from template"
)
return SandboxModelConverter.to_sandbox_create_response(parsed)
except Exception as e:
logger.warning(f"Failed to create sandbox from template {template_id}: {e}")
raise ExceptionConverter.to_sandbox_exception(e) from e
def get_sandbox_info(self, sandbox_id: str) -> SandboxInfo:
try:
from opensandbox.api.lifecycle.api.sandboxes import get_sandboxes_sandbox_id
from opensandbox.api.lifecycle.models import Sandbox as ApiSandbox
response_obj = get_sandboxes_sandbox_id.sync_detailed(
client=self._get_client(),
sandbox_id=sandbox_id,
)
handle_api_error(response_obj, f"Get sandbox {sandbox_id}")
parsed = require_parsed(
response_obj, ApiSandbox, f"Get sandbox {sandbox_id}"
)
return SandboxModelConverter.to_sandbox_info(parsed)
except Exception as e:
logger.warning(f"Failed to get sandbox info {sandbox_id}: {e}")
raise ExceptionConverter.to_sandbox_exception(e) from e
def list_sandboxes(self, filter: SandboxFilter) -> PagedSandboxInfos:
metadata = (
encode_metadata_filter(filter.metadata) if filter.metadata else UNSET
)
try:
from opensandbox.api.lifecycle.api.sandboxes import get_sandboxes
from opensandbox.api.lifecycle.models import (
ListSandboxesResponse as ApiListSandboxesResponse,
)
from opensandbox.api.lifecycle.types import UNSET as API_UNSET
response_obj = get_sandboxes.sync_detailed(
client=self._get_client(),
state=filter.states if filter.states else API_UNSET,
metadata=metadata,
page=filter.page if filter.page is not None else API_UNSET,
page_size=filter.page_size
if filter.page_size is not None
else API_UNSET,
)
handle_api_error(response_obj, "List sandboxes")
parsed = require_parsed(
response_obj, ApiListSandboxesResponse, "List sandboxes"
)
return SandboxModelConverter.to_paged_sandbox_infos(parsed)
except Exception as e:
logger.warning(f"Failed to list sandboxes: {e}")
raise ExceptionConverter.to_sandbox_exception(e) from e
def patch_sandbox_metadata(
self, sandbox_id: str, patch: dict[str, str | None]
) -> SandboxInfo:
try:
from opensandbox.api.lifecycle.api.sandboxes import (
patch_sandboxes_sandbox_id_metadata,
)
from opensandbox.api.lifecycle.models import PatchSandboxMetadataRequest
from opensandbox.api.lifecycle.models import Sandbox as ApiSandbox
response_obj = patch_sandboxes_sandbox_id_metadata.sync_detailed(
client=self._get_client(),
sandbox_id=sandbox_id,
body=PatchSandboxMetadataRequest.from_dict(patch),
)
handle_api_error(response_obj, f"Patch sandbox {sandbox_id} metadata")
parsed = require_parsed(
response_obj,
ApiSandbox,
f"Patch sandbox {sandbox_id} metadata",
)
return SandboxModelConverter.to_sandbox_info(parsed)
except Exception as e:
logger.warning(f"Failed to patch sandbox {sandbox_id} metadata: {e}")
raise ExceptionConverter.to_sandbox_exception(e) from e
def get_sandbox_endpoint(
self, sandbox_id: str, port: int, use_server_proxy: bool = False
) -> SandboxEndpoint:
if self._endpoint_cache is not None:
key = (sandbox_id, port, use_server_proxy)
return self._endpoint_cache.get_or_fetch(
key,
lambda: self._fetch_sandbox_endpoint(
sandbox_id, port, use_server_proxy
),
)
return self._fetch_sandbox_endpoint(sandbox_id, port, use_server_proxy)
def _fetch_sandbox_endpoint(
self, sandbox_id: str, port: int, use_server_proxy: bool = False
) -> SandboxEndpoint:
try:
from opensandbox.api.lifecycle.api.sandboxes import (
get_sandboxes_sandbox_id_endpoints_port,
)
from opensandbox.api.lifecycle.models import Endpoint as ApiEndpoint
response_obj = get_sandboxes_sandbox_id_endpoints_port.sync_detailed(
sandbox_id=sandbox_id,
port=port,
client=self._get_client(),
use_server_proxy=use_server_proxy,
)
handle_api_error(
response_obj, f"Get endpoint for sandbox {sandbox_id} port {port}"
)
parsed = require_parsed(response_obj, ApiEndpoint, "Get endpoint")
return SandboxModelConverter.to_sandbox_endpoint(
parsed, origin=self._sandbox_origin(response_obj)
)
except Exception as e:
logger.warning(
f"Failed to retrieve sandbox endpoint for sandbox {sandbox_id}: {e}"
)
raise ExceptionConverter.to_sandbox_exception(e) from e
@staticmethod
def _sandbox_origin(response_obj: object) -> str | None:
"""Extract the OPEN-SANDBOX-ORIGIN response header when present."""
headers = getattr(response_obj, "headers", None)
if headers is None:
return None
value = headers.get("OPEN-SANDBOX-ORIGIN")
return value or None
def invalidate_endpoint_cache(self, sandbox_id: str) -> None:
"""Remove all cached endpoints for a sandbox."""
if self._endpoint_cache is not None:
self._endpoint_cache.invalidate(sandbox_id)
def get_signed_sandbox_endpoint(
self,
sandbox_id: str,
port: int,
expires: int,
use_server_proxy: bool = False,
) -> SandboxEndpoint:
try:
from opensandbox.api.lifecycle.api.sandboxes import (
get_sandboxes_sandbox_id_endpoints_port,
)
from opensandbox.api.lifecycle.models import Endpoint as ApiEndpoint
response_obj = get_sandboxes_sandbox_id_endpoints_port.sync_detailed(
sandbox_id=sandbox_id,
port=port,
client=self._get_client(),
use_server_proxy=use_server_proxy,
expires=str(expires),
)
handle_api_error(
response_obj,
f"Get signed endpoint for sandbox {sandbox_id} port {port}",
)
parsed = require_parsed(response_obj, ApiEndpoint, "Get signed endpoint")
return SandboxModelConverter.to_sandbox_endpoint(
parsed, origin=self._sandbox_origin(response_obj)
)
except Exception as e:
logger.debug(
f"Failed to retrieve signed sandbox endpoint for sandbox {sandbox_id}",
exc_info=e,
)
raise ExceptionConverter.to_sandbox_exception(e) from e
def pause_sandbox(self, sandbox_id: str) -> None:
try:
from opensandbox.api.lifecycle.api.sandboxes import (
post_sandboxes_sandbox_id_pause,
)
response_obj = post_sandboxes_sandbox_id_pause.sync_detailed(
client=self._get_client(), sandbox_id=sandbox_id
)
handle_api_error(response_obj, f"Pause sandbox {sandbox_id}")
except Exception as e:
logger.warning(f"Failed to pause sandbox {sandbox_id}: {e}")
raise ExceptionConverter.to_sandbox_exception(e) from e
def resume_sandbox(self, sandbox_id: str) -> None:
try:
from opensandbox.api.lifecycle.api.sandboxes import (
post_sandboxes_sandbox_id_resume,
)
response_obj = post_sandboxes_sandbox_id_resume.sync_detailed(
client=self._get_client(), sandbox_id=sandbox_id
)
handle_api_error(response_obj, f"Resume sandbox {sandbox_id}")
except Exception as e:
logger.warning(f"Failed to resume sandbox {sandbox_id}: {e}")
raise ExceptionConverter.to_sandbox_exception(e) from e
def renew_sandbox_expiration(
self, sandbox_id: str, new_expiration_time: datetime
) -> SandboxRenewResponse:
try:
from opensandbox.api.lifecycle.api.sandboxes import (
post_sandboxes_sandbox_id_renew_expiration,
)
from opensandbox.api.lifecycle.models.renew_sandbox_expiration_response import (
RenewSandboxExpirationResponse,
)
renew_request = SandboxModelConverter.to_api_renew_request(
new_expiration_time
)
response_obj = post_sandboxes_sandbox_id_renew_expiration.sync_detailed(
client=self._get_client(),
sandbox_id=sandbox_id,
body=renew_request,
)
handle_api_error(response_obj, f"Renew sandbox {sandbox_id} expiration")
parsed = require_parsed(
response_obj,
RenewSandboxExpirationResponse,
f"Renew sandbox {sandbox_id} expiration",
)
return SandboxModelConverter.to_sandbox_renew_response(parsed)
except Exception as e:
logger.debug(f"Failed to renew sandbox {sandbox_id} expiration", exc_info=e)
raise ExceptionConverter.to_sandbox_exception(e) from e
def kill_sandbox(self, sandbox_id: str) -> None:
try:
from opensandbox.api.lifecycle.api.sandboxes import (
delete_sandboxes_sandbox_id,
)
response_obj = delete_sandboxes_sandbox_id.sync_detailed(
client=self._get_client(), sandbox_id=sandbox_id
)
handle_api_error(response_obj, f"Kill sandbox {sandbox_id}")
except Exception as e:
logger.warning(f"Failed to kill sandbox {sandbox_id}: {e}")
raise ExceptionConverter.to_sandbox_exception(e) from e
def create_snapshot(
self, sandbox_id: str, request: CreateSnapshotRequest | None = None
) -> SnapshotInfo:
try:
from opensandbox.api.lifecycle.api.snapshots import (
post_sandboxes_sandbox_id_snapshots,
)
from opensandbox.api.lifecycle.models import Snapshot as ApiSnapshot
response_obj = post_sandboxes_sandbox_id_snapshots.sync_detailed(
client=self._get_client(),
sandbox_id=sandbox_id,
body=SandboxModelConverter.to_api_create_snapshot_request(request),
)
handle_api_error(response_obj, f"Create snapshot for sandbox {sandbox_id}")
parsed = require_parsed(response_obj, ApiSnapshot, "Create snapshot")
return SandboxModelConverter.to_snapshot_info(parsed)
except Exception as e:
logger.warning(f"Failed to create snapshot for sandbox {sandbox_id}: {e}")
raise ExceptionConverter.to_sandbox_exception(e) from e
def get_snapshot(self, snapshot_id: str) -> SnapshotInfo:
try:
from opensandbox.api.lifecycle.api.snapshots import (
get_snapshots_snapshot_id,
)
from opensandbox.api.lifecycle.models import Snapshot as ApiSnapshot
response_obj = get_snapshots_snapshot_id.sync_detailed(
client=self._get_client(),
snapshot_id=snapshot_id,
)
handle_api_error(response_obj, f"Get snapshot {snapshot_id}")
parsed = require_parsed(
response_obj, ApiSnapshot, f"Get snapshot {snapshot_id}"
)
return SandboxModelConverter.to_snapshot_info(parsed)
except Exception as e:
logger.warning(f"Failed to get snapshot info {snapshot_id}: {e}")
raise ExceptionConverter.to_sandbox_exception(e) from e
def list_snapshots(self, filter: SnapshotFilter) -> PagedSnapshotInfos:
try:
from opensandbox.api.lifecycle.api.snapshots import get_snapshots
from opensandbox.api.lifecycle.models import (
ListSnapshotsResponse as ApiListSnapshotsResponse,
)
from opensandbox.api.lifecycle.types import UNSET as API_UNSET
response_obj = get_snapshots.sync_detailed(
client=self._get_client(),
sandbox_id=filter.sandbox_id
if filter.sandbox_id is not None
else API_UNSET,
name=filter.name if filter.name is not None else API_UNSET,
state=filter.states if filter.states else API_UNSET,
page=filter.page if filter.page is not None else API_UNSET,
page_size=filter.page_size
if filter.page_size is not None
else API_UNSET,
)
handle_api_error(response_obj, "List snapshots")
parsed = require_parsed(
response_obj, ApiListSnapshotsResponse, "List snapshots"
)
return SandboxModelConverter.to_paged_snapshot_infos(parsed)
except Exception as e:
logger.warning(f"Failed to list snapshots: {e}")
raise ExceptionConverter.to_sandbox_exception(e) from e
def delete_snapshot(self, snapshot_id: str) -> None:
try:
from opensandbox.api.lifecycle.api.snapshots import (
delete_snapshots_snapshot_id,
)
response_obj = delete_snapshots_snapshot_id.sync_detailed(
client=self._get_client(),
snapshot_id=snapshot_id,
)
handle_api_error(response_obj, f"Delete snapshot {snapshot_id}")
except Exception as e:
logger.warning(f"Failed to delete snapshot {snapshot_id}: {e}")
raise ExceptionConverter.to_sandbox_exception(e) from e
def create_template(self, request: CreateTemplateRequest) -> TemplateInfo:
try:
from opensandbox.api.lifecycle.api.templates import create_template
from opensandbox.api.lifecycle.models import FsbTemplate as ApiTemplate
response_obj = create_template.sync_detailed(
client=self._get_client(),
body=TemplateModelConverter.to_api_create_template_request(request),
)
handle_api_error(response_obj, "Create template")
parsed = require_parsed(response_obj, ApiTemplate, "Create template")
return TemplateModelConverter.to_template_info(parsed)
except Exception as e:
logger.warning(f"Failed to create template: {e}")
raise ExceptionConverter.to_sandbox_exception(e) from e
def get_template(self, template_id: str) -> TemplateInfo:
try:
from opensandbox.api.lifecycle.api.templates import get_template
from opensandbox.api.lifecycle.models import FsbTemplate as ApiTemplate
response_obj = get_template.sync_detailed(
client=self._get_client(),
template_id=template_id,
)
handle_api_error(response_obj, f"Get template {template_id}")
parsed = require_parsed(
response_obj, ApiTemplate, f"Get template {template_id}"
)
return TemplateModelConverter.to_template_info(parsed)
except Exception as e:
logger.warning(f"Failed to get template {template_id}: {e}")
raise ExceptionConverter.to_sandbox_exception(e) from e
def list_templates(self, filter: TemplateFilter) -> PagedTemplateInfos:
metadata = (
encode_metadata_filter(filter.metadata) if filter.metadata else UNSET
)
try:
from opensandbox.api.lifecycle.api.templates import list_templates
from opensandbox.api.lifecycle.models import (
ListFsbTemplatesResponse as ApiListTemplatesResponse,
)
from opensandbox.api.lifecycle.types import UNSET as API_UNSET
response_obj = list_templates.sync_detailed(
client=self._get_client(),
metadata=metadata,
page=filter.page if filter.page is not None else API_UNSET,
page_size=filter.page_size
if filter.page_size is not None
else API_UNSET,
)
handle_api_error(response_obj, "List templates")
parsed = require_parsed(
response_obj, ApiListTemplatesResponse, "List templates"
)
return TemplateModelConverter.to_paged_template_infos(parsed)
except Exception as e:
logger.warning(f"Failed to list templates: {e}")
raise ExceptionConverter.to_sandbox_exception(e) from e
def delete_template(self, template_id: str) -> None:
try:
from opensandbox.api.lifecycle.api.templates import delete_template
response_obj = delete_template.sync_detailed(
client=self._get_client(),
template_id=template_id,
)
handle_api_error(response_obj, f"Delete template {template_id}")
except Exception as e:
logger.warning(f"Failed to delete template {template_id}: {e}")
raise ExceptionConverter.to_sandbox_exception(e) from e