Skip to content

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

40.6 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.
#
"""
Synchronous Sandbox client implementation.
"""

import logging
import time
from collections.abc import Callable
from datetime import datetime, timedelta, timezone
from typing import Any

from opensandbox.config.connection_sync import ConnectionConfigSync
from opensandbox.constants import DEFAULT_EGRESS_PORT, DEFAULT_EXECD_PORT
from opensandbox.exceptions import (
    InvalidArgumentException,
    SandboxException,
    SandboxInternalException,
)
from opensandbox.internal.lifecycle_metrics import report_sandbox_create_metric
from opensandbox.internal.readiness import (
    ReadinessBudget,
    validate_polling_interval,
)
from opensandbox.models.diagnostics import DiagnosticContent, DiagnosticContext
from opensandbox.models.sandboxes import (
    CreateSnapshotRequest,
    CredentialProxyConfig,
    IdlePolicy,
    NetworkPolicy,
    NetworkRule,
    PlatformSpec,
    SandboxCreateResponse,
    SandboxEndpoint,
    SandboxImageSpec,
    SandboxInfo,
    SandboxLifecycle,
    SandboxMetrics,
    SandboxOrigin,
    SandboxRenewResponse,
    SnapshotInfo,
    Volume,
)
from opensandbox.sync.adapters.factory import AdapterFactorySync
from opensandbox.sync.services import (
    CommandsSync,
    CredentialVaultSync,
    DiagnosticsSync,
    EgressSync,
    FilesystemSync,
    HealthSync,
    IsolationServiceSync,
    MetricsSync,
    SandboxesSync,
)

logger = logging.getLogger(__name__)


class SandboxSync:
    """
    Main synchronous entrypoint for the Open Sandbox SDK.

    This class mirrors the async :class:`opensandbox.sandbox.Sandbox` API, but all
    operations are **blocking** and executed in the current thread.

    Key Features:

    - **Secure Isolation**: Complete Linux OS access in isolated containers
    - **File System Operations**: Create, read, update, delete files and directories
    - **Multi-language Execution**: Support for Python, Java, Bash, and other languages
    - **Real-time Command Execution**: Streaming output via SSE (Server-Sent Events)
    - **Resource Management**: CPU, memory, and storage constraints
    - **Lifecycle Management**: Create, pause, resume, terminate operations
    - **Health Monitoring**: Readiness polling and status tracking

    Notes:

    - **Blocking**: Do not call these methods directly from an asyncio event loop thread.
      If you need non-blocking behavior, prefer the async :class:`~opensandbox.sandbox.Sandbox`.
    - **Readiness timeouts**: Custom health checks and transports cannot be interrupted.
      They must bound their own blocking work; otherwise timeout is reported only
      after they return or raise.
    - **Resource cleanup**: :meth:`destroy` terminates the remote sandbox and closes local
      HTTP resources. Use :meth:`close` alone when the sandbox should remain available.

    Usage Example:

    ```python
    from datetime import timedelta
    from opensandbox.models.sandboxes import SandboxImageSpec
    from opensandbox.models.execd import RunCommandOpts
    from opensandbox.sync.sandbox import SandboxSync

    # Create a sandbox (blocking)
    sandbox = SandboxSync.create(
        "python:3.11",
        resource={"cpu": "1", "memory": "500Mi"},
        timeout=timedelta(minutes=30),
    )

    # Use the sandbox
    sandbox.files.write_file("script.py", "print('Hello World')")
    result = sandbox.commands.run("python script.py")

    # Always terminate the remote sandbox and close local resources
    sandbox.destroy()

    # Or use a context manager for automatic close():
    with SandboxSync.create("python:3.11") as sandbox:
        # Note on lifecycle:
        # - Exiting the context manager will call `sandbox.close()` (local HTTP resources only).
        # - You must still call `sandbox.kill()` to terminate the remote sandbox instance.
        sandbox.commands.run("python -c \"print('hi')\"")
        sandbox.kill()
    ```
    """

    def __init__(
        self,
        sandbox_id: str,
        sandbox_service: SandboxesSync,
        filesystem_service: FilesystemSync,
        command_service: CommandsSync,
        health_service: HealthSync,
        metrics_service: MetricsSync,
        egress_service: EgressSync,
        connection_config: ConnectionConfigSync,
        diagnostics_service: DiagnosticsSync | None = None,
        isolated_service: IsolationServiceSync | None = None,
        custom_health_check: Callable[["SandboxSync"], bool] | None = None,
        origin: str = SandboxOrigin.UNKNOWN,
    ) -> None:
        """
        Internal constructor for SandboxSync. Use :meth:`create` or :meth:`connect` instead.
        """
        self.id = sandbox_id
        self._sandbox_service = sandbox_service
        self._filesystem_service = filesystem_service
        self._command_service = command_service
        self._health_service = health_service
        self._metrics_service = metrics_service
        self._egress_service = egress_service
        self._connection_config = connection_config
        self._diagnostics_service = (
            diagnostics_service
            or AdapterFactorySync(connection_config).create_diagnostics_service()
        )
        self._custom_health_check = custom_health_check
        self._isolated_service = isolated_service
        self._origin = origin

    @property
    def origin(self) -> str:
        """Origin of this sandbox (see :class:`SandboxOrigin`).

        ``template`` when the sandbox runs on a fsb golden-image template:
        set locally by ``create_from_template``, and reported by the
        server's ``OPEN-SANDBOX-ORIGIN`` response header otherwise (also
        honored for snapshot restores, which boot the template's published
        artifact set). ``unknown`` for everything else.

        Template-backed sandboxes route egress policy operations through
        the lifecycle control plane
        (``/sandboxes/{sandboxId}/networkpolicy``) instead of the
        sandbox-side egress sidecar.
        """
        return self._origin

    @property
    def isolation(self) -> IsolationServiceSync:
        """Provides access to namespace-isolated session operations (OSEP-0013)."""
        if self._isolated_service is None:
            raise SandboxInternalException("isolated service not initialized")
        return self._isolated_service

    @property
    def files(self) -> FilesystemSync:
        """
        Provides access to file system operations within the sandbox.

        Allows writing, reading, listing, and deleting files and directories.
        """
        return self._filesystem_service

    def files_with_identity(self, uid: int, gid: int) -> FilesystemSync:
        """Return an independent filesystem client using explicit Linux credentials.

        Requires identity-aware Execd; unsupported servers never trigger fallback.
        """
        from opensandbox.sync.adapters.filesystem_adapter import FilesystemAdapterSync

        if not isinstance(self._filesystem_service, FilesystemAdapterSync):
            raise NotImplementedError(
                "The selected filesystem adapter does not support execution identity"
            )
        return self._filesystem_service.with_identity(uid, gid)

    @property
    def commands(self) -> CommandsSync:
        """
        Provides access to command execution operations.

        Supports both one-shot command execution and SSE streaming output.
        """
        return self._command_service

    @property
    def metrics(self) -> MetricsSync:
        """
        Provides access to sandbox metrics and monitoring.

        Allows retrieving resource usage statistics (CPU, memory) and other performance metrics.
        """
        return self._metrics_service

    @property
    def credential_vault(self) -> CredentialVaultSync:
        """
        Provides access to sandbox-scoped Credential Vault operations.

        Sidecar-backed sandboxes write straight to the egress sidecar.
        Template-backed sandboxes route through the lifecycle server, which
        relays vault revisions to the egress-held vault (OSEP-0022): the ack
        is synchronous and values never appear on any read. A ``412`` patch
        failure means another writer won the revision — re-read and retry
        with the fresh ``expected_revision``.
        """
        return self._egress_service

    @property
    def diagnostics(self) -> DiagnosticsSync:
        """
        Provides access to sandbox diagnostic log and event descriptors.
        """
        return self._diagnostics_service

    @property
    def connection_config(self) -> ConnectionConfigSync:
        """Provides access to the connection configuration (including shared transport)."""
        return self._connection_config

    def get_info(self) -> SandboxInfo:
        """
        Get the current status of this sandbox.

        Returns:
            Current sandbox status including state and metadata

        Raises:
            SandboxException: if status cannot be retrieved
        """
        return self._sandbox_service.get_sandbox_info(self.id)

    def get_endpoint(self, port: int) -> SandboxEndpoint:
        """
        Get a specific network endpoint for this sandbox.

        Args:
            port: The port number to get the endpoint for

        Returns:
            Endpoint information including connection details

        Raises:
            SandboxException: if endpoint cannot be retrieved
        """
        return self._sandbox_service.get_sandbox_endpoint(
            self.id, port, self.connection_config.use_server_proxy
        )

    def get_signed_endpoint(self, port: int, expires: int) -> SandboxEndpoint:
        """
        Get a signed endpoint URL with an OSEP-0011 route token.

        Args:
            port: The port number to get the endpoint for
            expires: Unix epoch seconds for the signed route token expiry

        Returns:
            Endpoint information with a signed URL

        Raises:
            SandboxException: if endpoint cannot be retrieved
        """
        return self._sandbox_service.get_signed_sandbox_endpoint(
            self.id, port, expires, self.connection_config.use_server_proxy
        )

    def get_metrics(self) -> SandboxMetrics:
        """
        Get the current resource usage metrics for this sandbox.

        Returns:
            Current sandbox metrics including CPU, memory, and I/O statistics

        Raises:
            SandboxException: if metrics cannot be retrieved
        """
        return self._metrics_service.get_metrics(self.id)

    def get_diagnostic_context(self) -> DiagnosticContext:
        """Get the sandbox's runtime backend and diagnostic identifiers."""
        return self._diagnostics_service.get_context(self.id)

    def get_diagnostic_logs(self, scope: str) -> DiagnosticContent:
        """
        Get diagnostic log content for this sandbox.

        Args:
            scope: Required diagnostic scope such as "container", "lifecycle", or "all".
        """
        return self._diagnostics_service.get_logs(self.id, scope)

    def get_diagnostic_events(self, scope: str) -> DiagnosticContent:
        """
        Get diagnostic event content for this sandbox.

        Args:
            scope: Required diagnostic scope such as "runtime", "lifecycle", or "all".
        """
        return self._diagnostics_service.get_events(self.id, scope)

    def renew(self, timeout: timedelta) -> SandboxRenewResponse:
        """
        Set the sandbox expiration time.

        The new expiration time will be set to the current time plus the provided duration.
        This may shorten or extend the remaining lifetime. The creation-time
        server timeout limit does not apply.

        Args:
            timeout: Duration to add to the current time to set the new expiration

        Returns:
            Renew response including the new expiration time.

        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"Renewing sandbox {self.id} timeout, estimated expiration: {new_expiration}"
        )
        return self._sandbox_service.renew_sandbox_expiration(self.id, new_expiration)

    def patch_metadata(self, patch: dict[str, str | None]) -> SandboxInfo:
        """
        Patch sandbox metadata.

        String values add or replace keys; None deletes keys.
        """
        return self._sandbox_service.patch_sandbox_metadata(self.id, patch)

    def create_snapshot(self, name: str | None = None) -> SnapshotInfo:
        """Create a persistent snapshot from this sandbox (blocking)."""
        return self._sandbox_service.create_snapshot(
            self.id, CreateSnapshotRequest(name=name)
        )

    def get_egress_policy(self) -> NetworkPolicy:
        """
        Get current egress policy for this sandbox.
        """
        return self._egress_service.get_policy()

    def patch_egress_rules(self, rules: list[NetworkRule]) -> None:
        """
        Patch egress rules for this sandbox using sidecar merge semantics.

        Rules in this patch payload take priority over existing rules with the
        same target. Existing rules for other targets remain unchanged. Within a
        single patch payload, the first rule for a target wins.

        This operation does not replace the entire policy and does not change
        the current defaultAction.
        """
        self._egress_service.patch_rules(rules)

    def delete_egress_rules(self, targets: list[str]) -> None:
        """
        Delete egress rules for this sandbox by target.

        Each entry is a FQDN or wildcard domain. Matching rules are removed
        from the currently enforced policy. Targets not present in the policy
        are silently ignored (idempotent). The current defaultAction is
        preserved.
        """
        self._egress_service.delete_rules(targets)

    def pause(self) -> None:
        """
        Pause the sandbox while preserving its state.

        The sandbox will transition to PAUSED state and can be resumed later.
        All running processes will be suspended.

        Raises:
            SandboxException: if pause operation fails
        """
        logger.info(f"Pausing sandbox: {self.id}")
        self._sandbox_service.invalidate_endpoint_cache(self.id)
        self._sandbox_service.pause_sandbox(self.id)

    def kill(self) -> None:
        """
        Request irreversible termination of the remote sandbox. Returns when
        deletion is accepted; runtime cleanup may continue afterward.

        Note: This method does NOT close the local resources. Use :meth:`close` or
        the sync context manager to clean up local resources.

        Raises:
            SandboxException: if termination fails
        """
        logger.info(f"Killing sandbox: {self.id}")
        self._sandbox_service.invalidate_endpoint_cache(self.id)
        self._sandbox_service.kill_sandbox(self.id)

    def close(self) -> None:
        """
        Close local resources associated with this sandbox.

        This method closes HTTP client resources and other local resources.
        It does NOT terminate the remote sandbox instance. Call :meth:`kill` first
        if you want to terminate the remote sandbox.

        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()
            logger.debug(f"Closed resources for sandbox {self.id}")
        except Exception as e:
            logger.warning(
                f"Error closing resources for sandbox {self.id}: {e}", exc_info=True
            )

    def destroy(self) -> None:
        """
        Terminate the remote sandbox and close local resources.

        Local resources are always closed, even if terminating the remote sandbox
        fails. Any termination error is re-raised after local cleanup completes.

        Raises:
            SandboxException: if termination fails
        """
        try:
            self.kill()
        finally:
            self.close()

    def is_healthy(self) -> bool:
        """
        Check if the sandbox is healthy and responsive.

        Returns:
            True if sandbox is healthy, False otherwise
        """
        if self._custom_health_check:
            return self._custom_health_check(self)
        try:
            return self._health_service.ping(self.id)
        except Exception:
            return False

    def _probe_health(self) -> bool:
        """Probe readiness without hiding authentication failures."""
        if self._custom_health_check:
            return self._custom_health_check(self)
        return self._health_service.ping(self.id)

    def check_ready(self, timeout: timedelta, polling_interval: timedelta) -> None:
        """
        Wait for the sandbox to pass health checks with polling.

        Args:
            timeout: Health-check budget; see class notes for custom-code limits.
            polling_interval: Time between health check attempts

        Raises:
            SandboxReadyTimeoutException: if health check doesn't pass within timeout
            SandboxException: if health check fails
        """
        self._check_ready(ReadinessBudget(timeout, polling_interval))

    def _check_ready(self, budget: ReadinessBudget) -> None:
        context = (
            f"ConnectionConfig(domain={self.connection_config.get_domain()}, "
            f"use_server_proxy={self.connection_config.use_server_proxy})"
        )
        # Fast-fail on 401/403 applies only to the built-in /ping probe: a custom
        # health_check may legitimately poll an app whose authorization becomes
        # available asynchronously, so it keeps the retry-until-deadline behavior.
        budget.health_sync(
            self._probe_health,
            context,
            auth_fail_fast=self._custom_health_check is None,
        )

    @classmethod
    def create(
        cls,
        image: SandboxImageSpec | str | None = None,
        *,
        snapshot_id: str | None = None,
        timeout: timedelta | None = timedelta(minutes=10),
        ready_timeout: timedelta = timedelta(seconds=30),
        env: dict[str, str] | None = None,
        metadata: dict[str, str] | None = None,
        resource: dict[str, str] | None = None,
        resource_requests: dict[str, str] | None = None,
        platform: PlatformSpec | None = None,
        network_policy: NetworkPolicy | None = None,
        credential_proxy: CredentialProxyConfig | None = None,
        extensions: dict[str, str] | None = None,
        secure_access: bool = False,
        entrypoint: list[str] | None = None,
        volumes: list[Volume] | None = None,
        connection_config: ConnectionConfigSync | None = None,
        health_check: Callable[["SandboxSync"], bool] | None = None,
        health_check_polling_interval: timedelta = timedelta(milliseconds=200),
        skip_health_check: bool = False,
        lifecycle: SandboxLifecycle | None = None,
    ) -> "SandboxSync":
        """
        Create a new sandbox instance with the specified configuration (blocking).

        Args:
            image: Container image specification including image reference and optional auth
            timeout: Maximum sandbox lifetime. Pass None to require explicit cleanup.
            ready_timeout: Total budget for endpoint publication and health checks.
            env: Environment variables for the sandbox
            metadata: Custom metadata for the sandbox
            resource: Resource limits (CPU, memory, etc.)
            network_policy: Optional outbound network policy (egress).
            credential_proxy: Optional Credential Vault proxy startup settings.
            extensions: Opaque extension parameters passed through to the server as-is.
                Prefer namespaced keys (e.g. ``storage.id``).
            secure_access: Whether to enable secured access for sandbox endpoints.
            entrypoint: Command to run as entrypoint
            volumes: Optional list of volumes to mount in the sandbox.
            connection_config: Connection configuration
            health_check: Custom sync health check function
            health_check_polling_interval: Polling interval used while waiting for endpoint publication and readiness/health.
            skip_health_check: Skip health checks; endpoint publication is still awaited.
            lifecycle: Optional pre-start and periodic lifecycle hooks.

        Returns:
            Fully configured and ready SandboxSync instance

        Raises:
            SandboxException: if sandbox creation or initialization fails
        """
        if (image is None) == (snapshot_id is None):
            raise InvalidArgumentException(
                "Exactly one of image or snapshot_id must be specified"
            )
        if not skip_health_check:
            validate_polling_interval(health_check_polling_interval)

        config = (
            connection_config or ConnectionConfigSync()
        ).with_transport_if_missing()
        entrypoint = entrypoint or ["tail", "-f", "/dev/null"]
        env = env or {}
        metadata = metadata or {}
        resource = resource or {"cpu": "1", "memory": "2Gi"}
        extensions = extensions or {}

        if isinstance(image, str):
            image = SandboxImageSpec(image=image)

        startup_source = image.image if image is not None else snapshot_id
        timeout_log = (
            "manual-cleanup" if timeout is None else f"{timeout.total_seconds()}s"
        )
        logger.info(
            f"Creating sandbox with startup source: {startup_source} (timeout: {timeout_log})"
        )

        return cls._launch(
            config=config,
            startup_source=startup_source,
            timeout=timeout,
            ready_timeout=ready_timeout,
            health_check=health_check,
            health_check_polling_interval=health_check_polling_interval,
            skip_health_check=skip_health_check,
            create_call=lambda service: service.create_sandbox(
                spec=image,
                entrypoint=entrypoint,
                env=env,
                metadata=metadata,
                timeout=timeout,
                resource=resource,
                network_policy=network_policy,
                credential_proxy=credential_proxy,
                extensions=extensions,
                volumes=volumes,
                platform=platform,
                secure_access=secure_access,
                snapshot_id=snapshot_id,
                resource_requests=resource_requests,
                lifecycle=lifecycle,
            ),
        )

    @classmethod
    def create_from_template(
        cls,
        template_id: str,
        *,
        timeout: timedelta,
        ready_timeout: timedelta = timedelta(seconds=30),
        metadata: dict[str, str] | None = None,
        network_policy: NetworkPolicy | None = None,
        extensions: dict[str, str] | None = None,
        idle_policy: IdlePolicy | None = None,
        connection_config: ConnectionConfigSync | None = None,
        health_check: Callable[["SandboxSync"], bool] | None = None,
        health_check_polling_interval: timedelta = timedelta(milliseconds=200),
        skip_health_check: bool = False,
    ) -> "SandboxSync":
        """
        Create a new sandbox from a ``Succeeded`` fsb template (blocking).

        Template mode fixes the workload shape on the server: the entrypoint,
        env, resources, volumes, platform and lifecycle hooks of the sandbox come
        from the template's golden image and cannot be overridden here. Only
        metadata, network policy, extensions and the control-plane
        ``idle_policy`` (OSEP-0024 ``lifecycle.idlePolicy``) may accompany the
        template id, and the timeout is required.

        Args:
            template_id: ID of a ``Succeeded`` fsb template (see
                ``SandboxManagerSync.create_template``)
            timeout: Maximum sandbox lifetime (required in template mode)
            ready_timeout: Total budget for endpoint publication and health checks.
            metadata: Custom metadata for the sandbox
            network_policy: Optional outbound network policy (egress).
            extensions: Opaque extension parameters passed through to the server as-is.
                Prefer namespaced keys (e.g. ``storage.id``).
            idle_policy: Optional idle behavior (OSEP-0024, fast-sandbox only).
            connection_config: Connection configuration
            health_check: Custom sync health check function
            health_check_polling_interval: Polling interval used while waiting for endpoint publication and readiness/health.
            skip_health_check: Skip health checks; endpoint publication is still awaited.

        Returns:
            Fully configured and ready SandboxSync instance

        Raises:
            InvalidArgumentException: if template_id is blank
            SandboxException: if sandbox creation or initialization fails
        """
        if not template_id or not template_id.strip():
            raise InvalidArgumentException("Template ID must be specified")
        if not skip_health_check:
            validate_polling_interval(health_check_polling_interval)

        config = (
            connection_config or ConnectionConfigSync()
        ).with_transport_if_missing()
        logger.info(
            f"Creating sandbox from template: {template_id} "
            f"(timeout: {timeout.total_seconds()}s)"
        )

        return cls._launch(
            config=config,
            startup_source=f"template:{template_id}",
            timeout=timeout,
            ready_timeout=ready_timeout,
            health_check=health_check,
            health_check_polling_interval=health_check_polling_interval,
            skip_health_check=skip_health_check,
            create_call=lambda service: service.create_sandbox_from_template(
                template_id=template_id,
                timeout=timeout,
                metadata=metadata,
                network_policy=network_policy,
                extensions=extensions,
                idle_policy=idle_policy,
            ),
            origin=SandboxOrigin.TEMPLATE,
        )

    @classmethod
    def _launch(
        cls,
        *,
        config: ConnectionConfigSync,
        startup_source: str | None,
        timeout: timedelta | None,
        ready_timeout: timedelta,
        health_check: Callable[["SandboxSync"], bool] | None,
        health_check_polling_interval: timedelta,
        skip_health_check: bool,
        create_call: Callable[[SandboxesSync], SandboxCreateResponse],
        origin: str = SandboxOrigin.UNKNOWN,
    ) -> "SandboxSync":
        """Shared create flow: create remote sandbox, gather endpoints, attach, verify readiness."""
        factory = AdapterFactorySync(config)
        sandbox_id: str | None = None
        sandbox_service: SandboxesSync | None = None
        create_started = time.monotonic()

        try:
            sandbox_service = factory.create_sandbox_service()
            response = create_call(sandbox_service)
            sandbox_id = response.id
            budget = ReadinessBudget(ready_timeout, health_check_polling_interval)
            if origin == SandboxOrigin.TEMPLATE:
                # Template-backed (fsb) sandboxes have no sandbox-side egress
                # sidecar: policy operations go through the lifecycle control
                # plane.
                execd_endpoint = budget.endpoint_sync(
                    lambda: sandbox_service.get_sandbox_endpoint(
                        response.id, DEFAULT_EXECD_PORT, config.use_server_proxy
                    )
                )
                egress_service = factory.create_network_policy_service(response.id)
            else:
                execd_endpoint = budget.endpoint_sync(
                    lambda: sandbox_service.get_sandbox_endpoint(
                        response.id, DEFAULT_EXECD_PORT, config.use_server_proxy
                    )
                )
                egress_endpoint = budget.endpoint_sync(
                    lambda: sandbox_service.get_sandbox_endpoint(
                        response.id, DEFAULT_EGRESS_PORT, config.use_server_proxy
                    )
                )
                # The server is authoritative about the runtime backing: for
                # fsb- prefixed sandboxes it reports `template` even when the
                # create used a snapshotId (a restore boots the template's
                # published artifact set). Such sandboxes have no sidecar,
                # so the egress service is swapped for the control-plane
                # adapter and the fetched sidecar endpoint goes unused.
                origin = execd_endpoint.origin or origin
                if origin == SandboxOrigin.TEMPLATE:
                    logger.info(
                        "server reported origin=template for %s; routing "
                        "egress policy through the lifecycle control plane",
                        response.id,
                    )
                    egress_service = factory.create_network_policy_service(response.id)
                else:
                    egress_service = factory.create_egress_service(egress_endpoint)

            sandbox = cls(
                sandbox_id=response.id,
                sandbox_service=sandbox_service,
                filesystem_service=factory.create_filesystem_service(execd_endpoint),
                command_service=factory.create_command_service(execd_endpoint),
                health_service=factory.create_health_service(execd_endpoint),
                metrics_service=factory.create_metrics_service(execd_endpoint),
                egress_service=egress_service,
                diagnostics_service=factory.create_diagnostics_service(),
                isolated_service=factory.create_isolated_session_service(
                    execd_endpoint
                ),
                connection_config=config,
                custom_health_check=health_check,
                origin=origin,
            )

            if not skip_health_check:
                sandbox._check_ready(budget)
                logger.info(f"Sandbox {sandbox.id} is ready")
            else:
                logger.info(
                    f"Sandbox {sandbox.id} created (skip_health_check=true, sandbox may not be ready yet)"
                )

            report_sandbox_create_metric(
                config,
                sandbox_id=sandbox.id,
                image=startup_source,
                create_duration_ms=int((time.monotonic() - create_started) * 1000),
                success=True,
            )

            return sandbox
        except BaseException as e:
            report_sandbox_create_metric(
                config,
                sandbox_id=sandbox_id,
                image=startup_source,
                create_duration_ms=int((time.monotonic() - create_started) * 1000),
                success=False,
            )
            if sandbox_id and sandbox_service:
                try:
                    logger.warning(
                        f"Sandbox creation failed during initialization. Attempting to terminate zombie sandbox: {sandbox_id}"
                    )
                    sandbox_service.kill_sandbox(sandbox_id)
                except Exception as cleanup_ex:
                    logger.error(
                        f"Failed to clean up sandbox {sandbox_id} after creation failure",
                        exc_info=cleanup_ex,
                    )
            config.close_transport_if_owned()
            if not isinstance(e, Exception):
                raise
            if isinstance(e, SandboxException):
                raise
            raise SandboxInternalException(
                f"Internal exception when creating sandbox: {e}"
            ) from e

    @classmethod
    def connect(
        cls,
        sandbox_id: str,
        connection_config: ConnectionConfigSync | None = None,
        health_check: Callable[["SandboxSync"], bool] | None = None,
        connect_timeout: timedelta = timedelta(seconds=30),
        health_check_polling_interval: timedelta = timedelta(milliseconds=200),
        skip_health_check: bool = False,
    ) -> "SandboxSync":
        """
        Connect to an existing sandbox instance by ID (blocking).

        Args:
            sandbox_id: ID of the existing sandbox
            connection_config: Connection configuration
            health_check: Custom sync health check function
            connect_timeout: Total endpoint/health-check budget; see class timeout notes.
            health_check_polling_interval: Polling interval used while waiting for readiness/health.
            skip_health_check: Skip health checks; endpoint publication is still awaited.

        Returns:
            Connected SandboxSync instance

        Raises:
            InvalidArgumentException: if required configuration is missing
            SandboxException: if sandbox connection fails
        """
        if not sandbox_id:
            raise InvalidArgumentException("Sandbox ID must be specified")
        sandbox_id = str(sandbox_id)

        config = (
            connection_config or ConnectionConfigSync()
        ).with_transport_if_missing()
        logger.info(f"Connecting to sandbox: {sandbox_id}")
        factory = AdapterFactorySync(config)

        try:
            sandbox_service = factory.create_sandbox_service()
            budget = ReadinessBudget(connect_timeout, health_check_polling_interval)
            execd_endpoint = budget.endpoint_sync(
                lambda: sandbox_service.get_sandbox_endpoint(
                    sandbox_id, DEFAULT_EXECD_PORT, config.use_server_proxy
                )
            )
            origin = execd_endpoint.origin or SandboxOrigin.UNKNOWN
            if origin == SandboxOrigin.TEMPLATE:
                # Template-backed (fsb) sandboxes have no sandbox-side egress
                # sidecar: policy operations go through the lifecycle control
                # plane, and the egress sidecar endpoint is never resolved.
                egress_service = factory.create_network_policy_service(sandbox_id)
            else:
                egress_endpoint = budget.endpoint_sync(
                    lambda: sandbox_service.get_sandbox_endpoint(
                        sandbox_id, DEFAULT_EGRESS_PORT, config.use_server_proxy
                    )
                )
                egress_service = factory.create_egress_service(egress_endpoint)

            sandbox = cls(
                sandbox_id=sandbox_id,
                sandbox_service=sandbox_service,
                filesystem_service=factory.create_filesystem_service(execd_endpoint),
                command_service=factory.create_command_service(execd_endpoint),
                health_service=factory.create_health_service(execd_endpoint),
                metrics_service=factory.create_metrics_service(execd_endpoint),
                egress_service=egress_service,
                diagnostics_service=factory.create_diagnostics_service(),
                isolated_service=factory.create_isolated_session_service(
                    execd_endpoint
                ),
                connection_config=config,
                custom_health_check=health_check,
                origin=origin,
            )

            if not skip_health_check:
                sandbox._check_ready(budget)
            else:
                logger.info(
                    f"Connected to sandbox {sandbox_id} (skip_health_check=true, sandbox may not be ready yet)"
                )

            logger.info(f"Connected to sandbox {sandbox_id}")
            return sandbox
        except BaseException as e:
            config.close_transport_if_owned()
            if not isinstance(e, Exception) or isinstance(e, SandboxException):
                raise
            raise SandboxInternalException(f"Failed to connect to sandbox: {e}") from e

    @classmethod
    def resume(
        cls,
        sandbox_id: str,
        connection_config: ConnectionConfigSync | None = None,
        health_check: Callable[["SandboxSync"], bool] | None = None,
        resume_timeout: timedelta = timedelta(seconds=30),
        health_check_polling_interval: timedelta = timedelta(milliseconds=200),
        skip_health_check: bool = False,
    ) -> "SandboxSync":
        """
        Resume a paused sandbox by ID and return a new, usable SandboxSync instance.

        This method performs the server-side resume operation, then re-resolves the execd endpoint
        (which may change across pause/resume on some backends), rebuilds service adapters, and
        optionally waits for readiness/health.

        Args:
            sandbox_id: ID of the paused sandbox to resume.
            connection_config: Connection configuration (shared transport, headers, timeouts).
            health_check: Optional custom sync health check function (falls back to ping).
            resume_timeout: Total endpoint/health-check budget after the resume request
                completes; see class timeout notes.
            health_check_polling_interval: Polling interval used while waiting for readiness/health.
            skip_health_check: Skip health checks; endpoint publication is still awaited.
        """
        if not sandbox_id:
            raise InvalidArgumentException("Sandbox ID must be specified")

        sandbox_id = str(sandbox_id)
        validate_polling_interval(health_check_polling_interval)

        config = (
            connection_config or ConnectionConfigSync()
        ).with_transport_if_missing()

        logger.info(f"Resuming sandbox: {sandbox_id}")
        factory = AdapterFactorySync(config)

        try:
            sandbox_service = factory.create_sandbox_service()
            sandbox_service.resume_sandbox(sandbox_id)

            budget = ReadinessBudget(resume_timeout, health_check_polling_interval)
            execd_endpoint = budget.endpoint_sync(
                lambda: sandbox_service.get_sandbox_endpoint(
                    sandbox_id, DEFAULT_EXECD_PORT, config.use_server_proxy
                )
            )
            origin = execd_endpoint.origin or SandboxOrigin.UNKNOWN
            if origin == SandboxOrigin.TEMPLATE:
                # Template-backed (fsb) sandboxes have no sandbox-side egress
                # sidecar: policy operations go through the lifecycle control
                # plane, and the egress sidecar endpoint is never resolved.
                egress_service = factory.create_network_policy_service(sandbox_id)
            else:
                egress_endpoint = budget.endpoint_sync(
                    lambda: sandbox_service.get_sandbox_endpoint(
                        sandbox_id, DEFAULT_EGRESS_PORT, config.use_server_proxy
                    )
                )
                egress_service = factory.create_egress_service(egress_endpoint)

            sandbox = cls(
                sandbox_id=sandbox_id,
                sandbox_service=sandbox_service,
                filesystem_service=factory.create_filesystem_service(execd_endpoint),
                command_service=factory.create_command_service(execd_endpoint),
                health_service=factory.create_health_service(execd_endpoint),
                metrics_service=factory.create_metrics_service(execd_endpoint),
                egress_service=egress_service,
                diagnostics_service=factory.create_diagnostics_service(),
                isolated_service=factory.create_isolated_session_service(
                    execd_endpoint
                ),
                connection_config=config,
                custom_health_check=health_check,
                origin=origin,
            )

            if not skip_health_check:
                sandbox._check_ready(budget)
            else:
                logger.info(
                    f"Resumed sandbox {sandbox_id} (skip_health_check=true, sandbox may not be ready yet)"
                )

            return sandbox
        except BaseException as e:
            config.close_transport_if_owned()
            if not isinstance(e, Exception) or isinstance(e, SandboxException):
                raise
            raise SandboxInternalException(f"Failed to resume sandbox: {e}") from e

    def __enter__(self) -> "SandboxSync":
        """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()