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