Skip to content

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

6.8 KB
Raw Blame
#
# Copyright 2026 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.
#

from __future__ import annotations

from collections.abc import Mapping
from typing import TYPE_CHECKING, Any, TypeVar

from attrs import define as _attrs_define

from ..types import UNSET, Unset

if TYPE_CHECKING:
    from ..models.idle_policy import IdlePolicy
    from ..models.lifecycle_hook import LifecycleHook
    from ..models.periodic_lifecycle_hook import PeriodicLifecycleHook
    from ..models.renewal_policy import RenewalPolicy


T = TypeVar("T", bound="SandboxLifecycle")


@_attrs_define
class SandboxLifecycle:
    """Extensible container for sandbox lifecycle configuration. All fields
    are optional. Future lifecycle events are added as new optional
    fields without changing the semantics of existing fields.

    `preStart` and `periodic` are hooks executed inside the sandbox by
    execd. `idlePolicy` (OSEP-0024) and `renewalPolicy` (OSEP-0009) are
    control-plane policies: they tell the server how to treat the
    sandbox's state machine and never reach the guest.

        Attributes:
            pre_start (LifecycleHook | Unset): A lifecycle command executed directly as an argv array. No implicit shell
                expansion is performed. Use an explicit shell command such as
                `["sh", "-c", "..."]` when shell syntax is required.
            periodic (list[PeriodicLifecycleHook] | Unset): Scheduled hooks run by execd while the sandbox is running. Runs
                of
                the same named hook never overlap; a scheduled run is skipped when
                its previous run is still active.
            idle_policy (IdlePolicy | Unset): Idle behavior declared by the sandbox (OSEP-0024). The policy is
                desired state: the server validates it and persists it as the
                reserved `sandbox.opensandbox.io/idle-policy` Sandbox CR annotation.

                With `idleTimeoutSeconds`, the sandbox is auto-paused after that many
                seconds without ingress-observed activity. Without it, the policy is
                wake-only: the sandbox is never auto-paused, but a (manually) paused
                sandbox wakes on access. A missing, malformed, or invalid policy is
                treated exactly as absent — never as an implicit opt-in.

                Constraints: `idleTimeoutSeconds` must not exceed the server's
                configured activity TTL (default 1800), so a present-but-stale
                activity key always implies idle-by-value. Enabling deployment flags
                never changes the behavior of sandboxes that do not declare a policy.
            renewal_policy (RenewalPolicy | Unset): Renew-on-access behavior declared by the sandbox (OSEP-0009). The
                policy is desired control-plane state: when the ingress gateway or
                the server proxy observes traffic for the sandbox, the server extends
                the sandbox expiration without client involvement. The policy never
                reaches the guest.

                Setting the policy has no effect unless the server operator enabled
                the renew-intent integration (`[renew_intent]`). A missing policy
                means the sandbox never auto-renews.
    """

    pre_start: LifecycleHook | Unset = UNSET
    periodic: list[PeriodicLifecycleHook] | Unset = UNSET
    idle_policy: IdlePolicy | Unset = UNSET
    renewal_policy: RenewalPolicy | Unset = UNSET

    def to_dict(self) -> dict[str, Any]:
        pre_start: dict[str, Any] | Unset = UNSET
        if not isinstance(self.pre_start, Unset):
            pre_start = self.pre_start.to_dict()

        periodic: list[dict[str, Any]] | Unset = UNSET
        if not isinstance(self.periodic, Unset):
            periodic = []
            for periodic_item_data in self.periodic:
                periodic_item = periodic_item_data.to_dict()
                periodic.append(periodic_item)

        idle_policy: dict[str, Any] | Unset = UNSET
        if not isinstance(self.idle_policy, Unset):
            idle_policy = self.idle_policy.to_dict()

        renewal_policy: dict[str, Any] | Unset = UNSET
        if not isinstance(self.renewal_policy, Unset):
            renewal_policy = self.renewal_policy.to_dict()

        field_dict: dict[str, Any] = {}

        field_dict.update({})
        if pre_start is not UNSET:
            field_dict["preStart"] = pre_start
        if periodic is not UNSET:
            field_dict["periodic"] = periodic
        if idle_policy is not UNSET:
            field_dict["idlePolicy"] = idle_policy
        if renewal_policy is not UNSET:
            field_dict["renewalPolicy"] = renewal_policy

        return field_dict

    @classmethod
    def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T:
        from ..models.idle_policy import IdlePolicy
        from ..models.lifecycle_hook import LifecycleHook
        from ..models.periodic_lifecycle_hook import PeriodicLifecycleHook
        from ..models.renewal_policy import RenewalPolicy

        d = dict(src_dict)
        _pre_start = d.pop("preStart", UNSET)
        pre_start: LifecycleHook | Unset
        if isinstance(_pre_start, Unset):
            pre_start = UNSET
        else:
            pre_start = LifecycleHook.from_dict(_pre_start)

        _periodic = d.pop("periodic", UNSET)
        periodic: list[PeriodicLifecycleHook] | Unset = UNSET
        if _periodic is not UNSET:
            periodic = []
            for periodic_item_data in _periodic:
                periodic_item = PeriodicLifecycleHook.from_dict(periodic_item_data)

                periodic.append(periodic_item)

        _idle_policy = d.pop("idlePolicy", UNSET)
        idle_policy: IdlePolicy | Unset
        if isinstance(_idle_policy, Unset):
            idle_policy = UNSET
        else:
            idle_policy = IdlePolicy.from_dict(_idle_policy)

        _renewal_policy = d.pop("renewalPolicy", UNSET)
        renewal_policy: RenewalPolicy | Unset
        if isinstance(_renewal_policy, Unset):
            renewal_policy = UNSET
        else:
            renewal_policy = RenewalPolicy.from_dict(_renewal_policy)

        sandbox_lifecycle = cls(
            pre_start=pre_start,
            periodic=periodic,
            idle_policy=idle_policy,
            renewal_policy=renewal_policy,
        )

        return sandbox_lifecycle