Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

29.5 KB
Raw Blame
#
# 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.
#
"""
Sandbox service adapter implementation.

Implementation of SandboxService that adapts openapi-python-client generated API.
This adapter provides a clean abstraction layer between business logic and
the auto-generated API client, handling all model conversions and error mapping.
"""

import logging
from datetime import datetime, timedelta
from urllib.parse import quote

import httpx  # type: ignore[reportMissingImports]

from opensandbox._httpx import build_async_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.api.lifecycle.types import UNSET
from opensandbox.config import ConnectionConfig
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.services.sandbox import Sandboxes

logger = logging.getLogger(__name__)


def encode_metadata_filter(metadata: dict[str, str]) -> str:
    """Percent-encode a metadata filter for the ``metadata`` query parameter.

    httpx percent-encodes the value once more and the server decodes its
    layer before splitting with ``parse_qsl``, so a single ``quote`` here
    round-trips keys and values containing ``&``, ``=`` or ``%``.
    """
    return "&".join(
        f"{quote(key, safe='')}={quote(value, safe='')}"
        for key, value in metadata.items()
    )


class SandboxesAdapter(Sandboxes):
    """
    Implementation of SandboxService that adapts openapi-python-client generated API.

    This adapter provides a clean abstraction layer between business logic and
    the sandbox management API, handling all model conversions and error mapping.

    The openapi-python-client generates functional APIs that support custom
    httpx.AsyncClient injection, allowing for fine-grained control over HTTP behavior.
    """

    def __init__(self, connection_config: ConnectionConfig) -> None:
        """
        Initialize the sandbox service adapter.

        Args:
            connection_config: Connection configuration (shared transport, headers, timeouts)
        """
        self.connection_config = connection_config

        from opensandbox.adapters.endpoint_cache import AsyncEndpointCache

        if not connection_config.endpoint_cache_disabled:
            self._endpoint_cache: AsyncEndpointCache | None = AsyncEndpointCache(
                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

        # Create client with custom auth header for OpenSandbox API
        self._client = AuthenticatedClient(
            base_url=self.connection_config.get_base_url(),
            token=api_key or "",
            prefix="",  # No prefix, just the token
            auth_header_name="OPEN-SANDBOX-API-KEY",  # Custom header name
            timeout=timeout,
            follow_redirects=self.connection_config.follow_redirects,
        )

        # Inject httpx client (adapter-owned)
        self._httpx_client = httpx.AsyncClient(
            base_url=self.connection_config.get_base_url(),
            headers=headers,
            timeout=timeout,
            transport=self.connection_config.transport,
            **build_async_redirect_client_options(
                self.connection_config,
                self.connection_config.get_base_url(),
            ),
        )
        self._client.set_async_httpx_client(self._httpx_client)

    async def _get_client(self):
        """Return the authenticated client for lifecycle API."""
        return self._client

    async 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:
        """Create a new sandbox instance with the specified configuration."""
        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

            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,
            )

            client = await self._get_client()
            response_obj = await post_sandboxes.asyncio_detailed(
                client=client,
                body=create_request,
            )

            handle_api_error(response_obj, "Create sandbox")

            from opensandbox.api.lifecycle.models import CreateSandboxResponse

            parsed = require_parsed(
                response_obj, CreateSandboxResponse, "Create sandbox"
            )
            response = SandboxModelConverter.to_sandbox_create_response(parsed)
            logger.info(f"Successfully created sandbox: {response.id}")
            return response

        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

    async 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:
        """Create a sandbox from a Succeeded fsb template."""
        logger.info(f"Creating sandbox from template: {template_id}")

        try:
            from opensandbox.api.lifecycle.api.sandboxes import post_sandboxes

            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,
            )

            client = await self._get_client()
            response_obj = await post_sandboxes.asyncio_detailed(
                client=client,
                body=create_request,
            )

            handle_api_error(response_obj, f"Create sandbox from template {template_id}")

            from opensandbox.api.lifecycle.models import CreateSandboxResponse

            parsed = require_parsed(
                response_obj, CreateSandboxResponse, "Create sandbox from template"
            )
            response = SandboxModelConverter.to_sandbox_create_response(parsed)
            logger.info(f"Successfully created sandbox from template: {response.id}")
            return response

        except Exception as e:
            logger.warning(f"Failed to create sandbox from template {template_id}: {e}")
            raise ExceptionConverter.to_sandbox_exception(e) from e

    async def get_sandbox_info(self, sandbox_id: str) -> SandboxInfo:
        """Retrieve detailed information about a sandbox."""
        logger.debug(f"Retrieving sandbox information: {sandbox_id}")

        try:
            from opensandbox.api.lifecycle.api.sandboxes import get_sandboxes_sandbox_id

            client = await self._get_client()
            response_obj = await get_sandboxes_sandbox_id.asyncio_detailed(
                client=client,
                sandbox_id=sandbox_id,
            )

            handle_api_error(response_obj, f"Get sandbox {sandbox_id}")

            from opensandbox.api.lifecycle.models import Sandbox

            parsed = require_parsed(response_obj, Sandbox, 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

    async def list_sandboxes(self, filter: SandboxFilter) -> PagedSandboxInfos:
        """List sandboxes with optional filtering criteria."""
        logger.debug(f"Listing sandboxes with filter: {filter}")

        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.types import UNSET as API_UNSET

            client = await self._get_client()
            response_obj = await get_sandboxes.asyncio_detailed(
                client=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")

            from opensandbox.api.lifecycle.models import ListSandboxesResponse

            parsed = require_parsed(
                response_obj, ListSandboxesResponse, "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

    async def patch_sandbox_metadata(
        self, sandbox_id: str, patch: dict[str, str | None]
    ) -> SandboxInfo:
        """Patch metadata for a sandbox using the metadata-specific lifecycle endpoint."""
        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

            client = await self._get_client()
            response_obj = await patch_sandboxes_sandbox_id_metadata.asyncio_detailed(
                client=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

    async 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

            client = await self._get_client()
            response_obj = await post_sandboxes_sandbox_id_snapshots.asyncio_detailed(
                client=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, Snapshot, "Create snapshot")
            return SandboxModelConverter.to_snapshot_info(parsed)
        except Exception as e:
            logger.debug(
                f"Failed to create snapshot for sandbox {sandbox_id}", exc_info=e
            )
            raise ExceptionConverter.to_sandbox_exception(e) from e

    async 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

            client = await self._get_client()
            response_obj = await get_snapshots_snapshot_id.asyncio_detailed(
                client=client,
                snapshot_id=snapshot_id,
            )
            handle_api_error(response_obj, f"Get snapshot {snapshot_id}")
            parsed = require_parsed(
                response_obj, Snapshot, 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

    async def list_snapshots(self, filter: SnapshotFilter) -> PagedSnapshotInfos:
        try:
            from opensandbox.api.lifecycle.api.snapshots import get_snapshots
            from opensandbox.api.lifecycle.models import ListSnapshotsResponse
            from opensandbox.api.lifecycle.types import UNSET as API_UNSET

            client = await self._get_client()
            response_obj = await get_snapshots.asyncio_detailed(
                client=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, ListSnapshotsResponse, "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

    async def delete_snapshot(self, snapshot_id: str) -> None:
        try:
            from opensandbox.api.lifecycle.api.snapshots import (
                delete_snapshots_snapshot_id,
            )

            client = await self._get_client()
            response_obj = await delete_snapshots_snapshot_id.asyncio_detailed(
                client=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

    async def create_template(self, request: CreateTemplateRequest) -> TemplateInfo:
        """Create a fsb template (golden-image build)."""
        logger.info(f"Creating template for image: {request.image}")

        try:
            from opensandbox.api.lifecycle.api.templates import create_template
            from opensandbox.api.lifecycle.models import FsbTemplate

            client = await self._get_client()
            response_obj = await create_template.asyncio_detailed(
                client=client,
                body=TemplateModelConverter.to_api_create_template_request(request),
            )

            handle_api_error(response_obj, "Create template")

            parsed = require_parsed(response_obj, FsbTemplate, "Create template")
            template = TemplateModelConverter.to_template_info(parsed)
            logger.info(f"Template build accepted: {template.template_id}")
            return template

        except Exception as e:
            logger.warning(f"Failed to create template: {e}")
            raise ExceptionConverter.to_sandbox_exception(e) from e

    async def get_template(self, template_id: str) -> TemplateInfo:
        """Get one template with its latest build status."""
        try:
            from opensandbox.api.lifecycle.api.templates import get_template
            from opensandbox.api.lifecycle.models import FsbTemplate

            client = await self._get_client()
            response_obj = await get_template.asyncio_detailed(
                client=client,
                template_id=template_id,
            )

            handle_api_error(response_obj, f"Get template {template_id}")

            parsed = require_parsed(
                response_obj, FsbTemplate, 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

    async def list_templates(self, filter: TemplateFilter) -> PagedTemplateInfos:
        """List the current tenant's templates with optional filtering."""
        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
            from opensandbox.api.lifecycle.types import UNSET as API_UNSET

            client = await self._get_client()
            response_obj = await list_templates.asyncio_detailed(
                client=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, ListFsbTemplatesResponse, "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

    async def delete_template(self, template_id: str) -> None:
        """Delete a template."""
        logger.info(f"Deleting template: {template_id}")

        try:
            from opensandbox.api.lifecycle.api.templates import delete_template

            client = await self._get_client()
            response_obj = await delete_template.asyncio_detailed(
                client=client,
                template_id=template_id,
            )

            handle_api_error(response_obj, f"Delete template {template_id}")

            logger.info(f"Successfully deleted 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

    async def get_sandbox_endpoint(
        self, sandbox_id: str, port: int, use_server_proxy: bool = False
    ) -> SandboxEndpoint:
        """Get network endpoint information for a sandbox service."""
        if self._endpoint_cache is not None:
            key = (sandbox_id, port, use_server_proxy)
            return await self._endpoint_cache.get_or_fetch(
                key,
                lambda: self._fetch_sandbox_endpoint(
                    sandbox_id, port, use_server_proxy
                ),
            )
        return await self._fetch_sandbox_endpoint(sandbox_id, port, use_server_proxy)

    async def _fetch_sandbox_endpoint(
        self, sandbox_id: str, port: int, use_server_proxy: bool = False
    ) -> SandboxEndpoint:
        """Fetch endpoint from server (no cache)."""
        logger.debug(f"Retrieving sandbox endpoint: {sandbox_id}, port {port}")

        try:
            from opensandbox.api.lifecycle.api.sandboxes import (
                get_sandboxes_sandbox_id_endpoints_port,
            )

            client = await self._get_client()
            response_obj = (
                await get_sandboxes_sandbox_id_endpoints_port.asyncio_detailed(
                    client=client,
                    sandbox_id=sandbox_id,
                    port=port,
                    use_server_proxy=use_server_proxy,
                )
            )

            handle_api_error(
                response_obj, f"Get endpoint for sandbox {sandbox_id} port {port}"
            )

            from opensandbox.api.lifecycle.models import Endpoint

            parsed = require_parsed(response_obj, Endpoint, "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)

    async def get_signed_sandbox_endpoint(
        self,
        sandbox_id: str,
        port: int,
        expires: int,
        use_server_proxy: bool = False,
    ) -> SandboxEndpoint:
        """Get signed sandbox endpoint with an OSEP-0011 route token."""
        logger.debug(f"Retrieving signed sandbox endpoint: {sandbox_id}, port {port}")

        try:
            from opensandbox.api.lifecycle.api.sandboxes import (
                get_sandboxes_sandbox_id_endpoints_port,
            )

            client = await self._get_client()
            response_obj = (
                await get_sandboxes_sandbox_id_endpoints_port.asyncio_detailed(
                    client=client,
                    sandbox_id=sandbox_id,
                    port=port,
                    use_server_proxy=use_server_proxy,
                    expires=str(expires),
                )
            )

            handle_api_error(
                response_obj,
                f"Get signed endpoint for sandbox {sandbox_id} port {port}",
            )

            from opensandbox.api.lifecycle.models import Endpoint

            parsed = require_parsed(response_obj, Endpoint, "Get signed endpoint")
            return SandboxModelConverter.to_sandbox_endpoint(
                parsed, origin=self._sandbox_origin(response_obj)
            )

        except Exception as e:
            logger.warning(
                f"Failed to retrieve signed sandbox endpoint for sandbox {sandbox_id}: {e}"
            )
            raise ExceptionConverter.to_sandbox_exception(e) from e

    async def pause_sandbox(self, sandbox_id: str) -> None:
        """Pause a running sandbox while preserving its state."""
        logger.info(f"Pausing sandbox: {sandbox_id}")

        try:
            from opensandbox.api.lifecycle.api.sandboxes import (
                post_sandboxes_sandbox_id_pause,
            )

            client = await self._get_client()
            response_obj = await post_sandboxes_sandbox_id_pause.asyncio_detailed(
                client=client,
                sandbox_id=sandbox_id,
            )

            handle_api_error(response_obj, f"Pause sandbox {sandbox_id}")

            logger.info(f"Initiated pause for sandbox: {sandbox_id}")

        except Exception as e:
            logger.warning(f"Failed to initiate pause sandbox {sandbox_id}: {e}")
            raise ExceptionConverter.to_sandbox_exception(e) from e

    async def resume_sandbox(self, sandbox_id: str) -> None:
        """Resume a previously paused sandbox."""
        logger.info(f"Resuming sandbox: {sandbox_id}")

        try:
            from opensandbox.api.lifecycle.api.sandboxes import (
                post_sandboxes_sandbox_id_resume,
            )

            client = await self._get_client()
            response_obj = await post_sandboxes_sandbox_id_resume.asyncio_detailed(
                client=client,
                sandbox_id=sandbox_id,
            )

            handle_api_error(response_obj, f"Resume sandbox {sandbox_id}")

            logger.info(f"Initiated resume for 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

    async def renew_sandbox_expiration(
        self, sandbox_id: str, new_expiration_time: datetime
    ) -> SandboxRenewResponse:
        """Extend the expiration time of a sandbox."""
        logger.info(f"Renew sandbox {sandbox_id} expiration to {new_expiration_time}")

        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
            )

            client = await self._get_client()
            response_obj = (
                await post_sandboxes_sandbox_id_renew_expiration.asyncio_detailed(
                    client=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",
            )
            renew_response = SandboxModelConverter.to_sandbox_renew_response(parsed)
            logger.info(
                f"Successfully renewed sandbox {sandbox_id} expiration to {renew_response.expires_at}"
            )
            return renew_response

        except Exception as e:
            logger.warning(f"Failed to renew sandbox {sandbox_id} expiration: {e}")
            raise ExceptionConverter.to_sandbox_exception(e) from e

    async def kill_sandbox(self, sandbox_id: str) -> None:
        """Request termination; returns on accepted deletion. Cleanup may continue."""
        logger.info(f"Terminating sandbox: {sandbox_id}")

        try:
            from opensandbox.api.lifecycle.api.sandboxes import (
                delete_sandboxes_sandbox_id,
            )

            client = await self._get_client()
            response_obj = await delete_sandboxes_sandbox_id.asyncio_detailed(
                client=client,
                sandbox_id=sandbox_id,
            )

            handle_api_error(response_obj, f"Kill sandbox {sandbox_id}")

            logger.info(f"Sandbox deletion accepted: {sandbox_id}")

        except Exception as e:
            logger.warning(f"Failed to terminate sandbox {sandbox_id}: {e}")
            raise ExceptionConverter.to_sandbox_exception(e) from e