Skip to content

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

10.4 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 interface.

Protocol for sandbox lifecycle management operations.
"""

from datetime import datetime, timedelta
from typing import Protocol

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


class Sandboxes(Protocol):
    """
    Core sandbox lifecycle management service.

    This service provides a clean abstraction over sandbox creation, management,
    and termination operations, completely isolating business logic from API implementation details.
    """

    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 with the specified configuration.

        Args:
            spec: Container image specification for provisioning the sandbox.
            entrypoint: Command to run as the sandbox's main process.
            env: Environment variables injected into the sandbox runtime.
            metadata: User-defined metadata used for management and filtering.
            timeout: Sandbox lifetime. Pass None to create a sandbox that requires explicit cleanup.
            resource: Runtime resource limits (e.g. cpu/memory). Exact semantics are server-defined.
            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``).
            volumes: Optional list of volume mounts for persistent storage.
            secure_access: Whether to enable secured access for sandbox endpoints.
            lifecycle: Optional pre-start and periodic lifecycle hooks.

        Returns:
            Sandbox create response

        Raises:
            SandboxException: if the operation fails
        """
        ...

    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.

        Template mode fixes the workload shape on the server: only metadata,
        network policy, extensions and the control-plane ``idle_policy``
        may accompany the template id, and the timeout is required.

        Args:
            template_id: Succeeded fsb template to create the sandbox from
            timeout: Sandbox lifetime (required in template mode)
            metadata: User-defined metadata used for management and filtering
            network_policy: Optional outbound network policy (egress)
            extensions: Opaque extension parameters passed through to the server as-is
            idle_policy: Optional idle behavior (OSEP-0024, fast-sandbox only)

        Returns:
            Sandbox create response

        Raises:
            SandboxException: if the operation fails
        """
        ...

    async def get_sandbox_info(self, sandbox_id: str) -> SandboxInfo:
        """
        Retrieve information about an existing sandbox.

        Args:
            sandbox_id: Unique identifier of the sandbox

        Returns:
            Current sandbox information

        Raises:
            SandboxException: if the operation fails
        """
        ...

    async def list_sandboxes(self, filter: SandboxFilter) -> PagedSandboxInfos:
        """
        List sandboxes with optional filtering.

        Args:
            filter: Optional filter criteria

        Returns:
            List of sandbox information matching the filter

        Raises:
            SandboxException: if the operation fails
        """
        ...

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

        Args:
            sandbox_id: Unique identifier of the sandbox
            patch: Metadata merge patch. String values add or replace keys; None deletes keys.

        Returns:
            Current sandbox information after applying the patch

        Raises:
            SandboxException: if the operation fails
        """
        ...

    async def get_sandbox_endpoint(
        self, sandbox_id: str, port: int, use_server_proxy: bool = False
    ) -> SandboxEndpoint:
        """
        Get sandbox endpoint.

        Args:
            sandbox_id: Sandbox ID
            port: Endpoint port number
            use_server_proxy: Whether to use server proxy for endpoint

        Returns:
            Target sandbox endpoint

        Raises:
            SandboxException: if the operation fails
        """
        ...

    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.

        Args:
            sandbox_id: Sandbox ID
            port: Endpoint port number
            expires: Unix epoch seconds for the signed route token expiry
            use_server_proxy: Whether to use server proxy for endpoint

        Returns:
            Target sandbox endpoint

        Raises:
            SandboxException: if the operation fails
        """
        ...

    async def pause_sandbox(self, sandbox_id: str) -> None:
        """
        Pause a running sandbox, preserving its state.

        Args:
            sandbox_id: Unique identifier of the sandbox

        Raises:
            SandboxException: if the operation fails
        """
        ...

    async def resume_sandbox(self, sandbox_id: str) -> None:
        """
        Resume a paused sandbox.

        Args:
            sandbox_id: Unique identifier of the sandbox

        Raises:
            SandboxException: if the operation fails
        """
        ...

    async def renew_sandbox_expiration(
        self, sandbox_id: str, new_expiration_time: datetime
    ) -> SandboxRenewResponse:
        """
        Renew the expiration time of a sandbox.

        Args:
            sandbox_id: Unique identifier of the sandbox
            new_expiration_time: New expiration timestamp

        Returns:
            Renew response including the new expiration time.

        Raises:
            SandboxException: if the operation fails
        """
        ...

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

        Args:
            sandbox_id: Unique identifier of the sandbox

        Raises:
            SandboxException: if the operation fails
        """
        ...

    async def create_snapshot(
        self, sandbox_id: str, request: CreateSnapshotRequest | None = None
    ) -> SnapshotInfo:
        """Create a persistent snapshot from a sandbox."""
        ...

    async def get_snapshot(self, snapshot_id: str) -> SnapshotInfo:
        """Retrieve information about an existing snapshot."""
        ...

    async def list_snapshots(self, filter: SnapshotFilter) -> PagedSnapshotInfos:
        """List snapshots with optional filtering."""
        ...

    async def delete_snapshot(self, snapshot_id: str) -> None:
        """Delete a snapshot."""
        ...

    async def create_template(self, request: CreateTemplateRequest) -> TemplateInfo:
        """
        Create a fsb template (golden-image build).

        The build runs asynchronously: the response carries
        ``status.phase: Pending``; poll ``get_template`` until ``Succeeded``
        (or ``Failed``). Only ``Succeeded`` templates can back template-based
        sandbox creation.

        Raises:
            SandboxException: if the operation fails
        """
        ...

    async def get_template(self, template_id: str) -> TemplateInfo:
        """
        Get one template with its latest build status.

        Raises:
            SandboxException: if the operation fails
        """
        ...

    async def list_templates(self, filter: TemplateFilter) -> PagedTemplateInfos:
        """
        List the current tenant's templates with optional metadata filtering
        (AND logic) and pagination.

        Raises:
            SandboxException: if the operation fails
        """
        ...

    async def delete_template(self, template_id: str) -> None:
        """
        Delete a template.

        Sandboxes already created from the template are unaffected.

        Raises:
            SandboxException: if the operation fails
        """
        ...

    def invalidate_endpoint_cache(self, sandbox_id: str) -> None:
        """Remove all cached endpoints for a sandbox. No-op if caching is disabled."""
        ...