Skip to content

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

11.2 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.

"""Shared constants for sandbox services."""

from opensandbox_server.constants import OPENSANDBOX_LIFECYCLE

RESERVED_LABEL_PREFIX = "opensandbox.io/"

SANDBOX_ID_LABEL = "opensandbox.io/id"
SANDBOX_TENANT_LABEL = "opensandbox.io/tenant"
SANDBOX_EXPIRES_AT_LABEL = "opensandbox.io/expires-at"
SANDBOX_CREATED_AT_LABEL = "opensandbox.io/created-at"
SANDBOX_MANUAL_CLEANUP_LABEL = "opensandbox.io/manual-cleanup"
SANDBOX_PLATFORM_OS_LABEL = "opensandbox.io/platform-os"
SANDBOX_PLATFORM_ARCH_LABEL = "opensandbox.io/platform-arch"
SANDBOX_SNAPSHOT_ID_LABEL = "opensandbox.io/snapshot-id"
# JSON list of the user metadata keys set at create (Docker): the container
# also carries labels inherited from its image, which are not metadata.
SANDBOX_METADATA_KEYS_LABEL = "opensandbox.io/metadata-keys"
# Host-mapped ports recorded on containers (bridge mode).
SANDBOX_EMBEDDING_PROXY_PORT_LABEL = (
    "opensandbox.io/embedding-proxy-port"  # maps container 44772 -> host port
)
SANDBOX_HTTP_PORT_LABEL = "opensandbox.io/http-port"  # maps container 8080 -> host port
SANDBOX_OSSFS_MOUNTS_LABEL = "opensandbox.io/ossfs-mounts"
SANDBOX_MANAGED_VOLUMES_LABEL = "opensandbox.io/volume-managed-by"
OPEN_SANDBOX_INGRESS_HEADER = "OpenSandbox-Ingress-To"
OPEN_SANDBOX_EGRESS_AUTH_HEADER = "OPENSANDBOX-EGRESS-AUTH"
# Response header published by the lifecycle server on endpoint lookups:
# tells clients the origin of a sandbox (e.g. "template" for fsb
# golden-image sandboxes, which have no sandbox-side egress sidecar).
OPEN_SANDBOX_ORIGIN_HEADER = "OPEN-SANDBOX-ORIGIN"
SANDBOX_ORIGIN_TEMPLATE = "template"
SANDBOX_EGRESS_AUTH_TOKEN_METADATA_KEY = "opensandbox.io/egress-auth-token"
OPEN_SANDBOX_SECURE_ACCESS_HEADER = "OpenSandbox-Secure-Access"
SANDBOX_SECURE_ACCESS_TOKEN_METADATA_KEY = "opensandbox.io/secure-access-token"

# Environment variable name for passing network policy to egress sidecar
EGRESS_RULES_ENV = "OPENSANDBOX_EGRESS_RULES"
# Must match components/egress/pkg/constants/configuration.go EnvEgressMode
EGRESS_MODE_ENV = "OPENSANDBOX_EGRESS_MODE"
# Must match components/egress/pkg/constants/configuration.go EnvEgressToken
OPENSANDBOX_EGRESS_TOKEN = "OPENSANDBOX_EGRESS_TOKEN"
OPENSANDBOX_EGRESS_MITMPROXY_TRANSPARENT = "OPENSANDBOX_EGRESS_MITMPROXY_TRANSPARENT"
# Server-injected; not user-settable.
OPENSANDBOX_EGRESS_SANDBOX_ID = "OPENSANDBOX_EGRESS_SANDBOX_ID"
# Server-injected from [egress].otlp_endpoint; not user-settable. Must be http(s):
# the egress telemetry client only speaks OTLP over HTTP/protobuf.
OTEL_EXPORTER_OTLP_ENDPOINT = "OTEL_EXPORTER_OTLP_ENDPOINT"

EGRESS_ENV_PREFIX = "OPENSANDBOX_EGRESS_"
OPENSANDBOX_EGRESS_MITMPROXY_SSL_INSECURE = "OPENSANDBOX_EGRESS_MITMPROXY_SSL_INSECURE"
# Experimental: extra TCP dports to intercept, appended to the always-on 80,443.
# Must match components/egress/pkg/constants/configuration.go EnvMitmproxyExtraPorts.
OPENSANDBOX_EGRESS_MITMPROXY_EXTRA_PORTS = "OPENSANDBOX_EGRESS_MITMPROXY_EXTRA_PORTS"
OPENSANDBOX_EGRESS_CREDENTIAL_VAULT_TRUSTED_PROXY_CIDRS = (
    "OPENSANDBOX_EGRESS_CREDENTIAL_VAULT_TRUSTED_PROXY_CIDRS"
)
OPENSANDBOX_EGRESS_CREDENTIAL_VAULT_REQUIRE_SCOPED_MATCH = (
    "OPENSANDBOX_EGRESS_CREDENTIAL_VAULT_REQUIRE_SCOPED_MATCH"
)
# Server-injected from [egress.upstream_proxy]; admin-only, deliberately not in
# ALLOWED_EGRESS_ENV_VARS so request env cannot set them.
# Must match components/egress/pkg/constants/configuration.go EnvUpstreamProxy{,Auth}.
OPENSANDBOX_EGRESS_UPSTREAM_PROXY = "OPENSANDBOX_EGRESS_UPSTREAM_PROXY"
OPENSANDBOX_EGRESS_UPSTREAM_PROXY_AUTH = "OPENSANDBOX_EGRESS_UPSTREAM_PROXY_AUTH"
# Server-injected when [egress.upstream_proxy] configures a CA source;
# admin-only, deliberately not in ALLOWED_EGRESS_ENV_VARS so request env
# cannot set it. Must match components/egress/pkg/constants/configuration.go
# EnvMitmproxyUpstreamExtraCA.
OPENSANDBOX_EGRESS_MITMPROXY_UPSTREAM_EXTRA_CA = (
    "OPENSANDBOX_EGRESS_MITMPROXY_UPSTREAM_EXTRA_CA"
)
# Fixed in-sidecar mount point shared by the Docker bind and the Kubernetes
# Secret projection.
EGRESS_UPSTREAM_EXTRA_CA_PATH = (
    "/etc/ssl/certs/opensandbox-upstream-extra-ca.pem"
)
EGRESS_UPSTREAM_EXTRA_CA_VOLUME_NAME = "opensandbox-egress-upstream-extra-ca"
EGRESS_UPSTREAM_EXTRA_CA_SECRET_KEY = "ca.crt"
ALLOWED_EGRESS_ENV_VARS = frozenset({
    "OPENSANDBOX_EGRESS_LOG_LEVEL",
    "OPENSANDBOX_EGRESS_DNS_UPSTREAM_TIMEOUT",
    OPENSANDBOX_EGRESS_MITMPROXY_SSL_INSECURE,
    OPENSANDBOX_EGRESS_MITMPROXY_TRANSPARENT,
    OPENSANDBOX_EGRESS_MITMPROXY_EXTRA_PORTS,
    "OPENSANDBOX_EGRESS_DENY_WEBHOOK",
    "OPENSANDBOX_EGRESS_METRICS_EXTRA_ATTRS",
    "OPENSANDBOX_EGRESS_CREDENTIAL_VAULT_REQUIRE_TLS",
    OPENSANDBOX_EGRESS_CREDENTIAL_VAULT_REQUIRE_SCOPED_MATCH,
    OPENSANDBOX_EGRESS_CREDENTIAL_VAULT_TRUSTED_PROXY_CIDRS,
    "OPENSANDBOX_EGRESS_POLICY_FILE",
})
OPENSANDBOX_RUNTIME_VOLUME_NAME = "opensandbox-bin"
OPENSANDBOX_RUNTIME_MOUNT_PATH = "/opt/opensandbox"


class SandboxErrorCodes:
    """Canonical error codes for sandbox service operations."""

    # Docker runtime error codes
    DOCKER_INITIALIZATION_ERROR = "DOCKER::INITIALIZATION_ERROR"
    CONTAINER_QUERY_FAILED = "DOCKER::SANDBOX_QUERY_FAILED"
    SANDBOX_NOT_FOUND = "DOCKER::SANDBOX_NOT_FOUND"
    IMAGE_PULL_FAILED = "DOCKER::SANDBOX_IMAGE_PULL_FAILED"
    IMAGE_REMOVE_ERROR = "DOCKER::SNAPSHOT_IMAGE_REMOVE_FAILED"
    CONTAINER_START_FAILED = "DOCKER::SANDBOX_START_FAILED"
    SANDBOX_DELETE_FAILED = "DOCKER::SANDBOX_DELETE_FAILED"
    SANDBOX_NOT_RUNNING = "DOCKER::SANDBOX_NOT_RUNNING"
    SANDBOX_PAUSE_FAILED = "DOCKER::SANDBOX_PAUSE_FAILED"
    SANDBOX_NOT_PAUSED = "DOCKER::SANDBOX_NOT_PAUSED"
    SANDBOX_RESUME_FAILED = "DOCKER::SANDBOX_RESUME_FAILED"
    INVALID_EXPIRATION = "DOCKER::INVALID_EXPIRATION"
    EXPIRATION_NOT_EXTENDED = "DOCKER::EXPIRATION_NOT_EXTENDED"
    EXECD_START_FAILED = "DOCKER::SANDBOX_EXECD_START_FAILED"
    EXECD_DISTRIBUTION_FAILED = "DOCKER::SANDBOX_EXECD_DISTRIBUTION_FAILED"
    BOOTSTRAP_INSTALL_FAILED = "DOCKER::SANDBOX_BOOTSTRAP_INSTALL_FAILED"
    INVALID_ENTRYPOINT = "DOCKER::INVALID_ENTRYPOINT"
    INVALID_PORT = "DOCKER::INVALID_PORT"
    NETWORK_MODE_ENDPOINT_UNAVAILABLE = "DOCKER::NETWORK_MODE_ENDPOINT_UNAVAILABLE"

    # Kubernetes runtime error codes
    K8S_INITIALIZATION_ERROR = "KUBERNETES::INITIALIZATION_ERROR"
    K8S_SANDBOX_NOT_FOUND = "KUBERNETES::SANDBOX_NOT_FOUND"
    K8S_POD_FAILED = "KUBERNETES::POD_FAILED"
    K8S_POD_READY_TIMEOUT = "KUBERNETES::POD_READY_TIMEOUT"
    K8S_API_ERROR = "KUBERNETES::API_ERROR"
    K8S_POD_IP_NOT_AVAILABLE = "KUBERNETES::POD_IP_NOT_AVAILABLE"
    K8S_QUOTA_EXCEEDED = "KUBERNETES::QUOTA_EXCEEDED"

    # fsb (fast-sandbox) runtime error codes
    FSB_SANDBOX_NOT_FOUND = "FSB::SANDBOX_NOT_FOUND"
    FSB_POOL_NOT_FOUND = "FSB::POOL_NOT_FOUND"
    FSB_TEMPLATE_NOT_FOUND = "FSB::TEMPLATE_NOT_FOUND"
    FSB_TEMPLATE_CONFLICT = "FSB::TEMPLATE_CONFLICT"
    FSB_API_ERROR = "FSB::API_ERROR"
    FSB_UNSUPPORTED = "FSB::API_NOT_SUPPORTED"

    # Common error codes
    UNKNOWN_ERROR = "SANDBOX::UNKNOWN_ERROR"
    API_NOT_SUPPORTED = "SANDBOX::API_NOT_SUPPORTED"
    INVALID_METADATA_LABEL = "SANDBOX::INVALID_METADATA_LABEL"
    INVALID_PARAMETER = "SANDBOX::INVALID_PARAMETER"
    INTERNAL_ERROR = "SANDBOX::INTERNAL_ERROR"

    # Pool error codes
    K8S_POOL_NOT_FOUND = "KUBERNETES::POOL_NOT_FOUND"
    K8S_POOL_ALREADY_EXISTS = "KUBERNETES::POOL_ALREADY_EXISTS"
    K8S_POOL_API_ERROR = "KUBERNETES::POOL_API_ERROR"
    K8S_POOL_NOT_SUPPORTED = "KUBERNETES::POOL_NOT_SUPPORTED"
    K8S_POOL_CAPACITY_EXHAUSTED = "KUBERNETES::POOL_CAPACITY_EXHAUSTED"

    # Volume error codes
    INVALID_VOLUME_NAME = "VOLUME::INVALID_NAME"
    DUPLICATE_VOLUME_NAME = "VOLUME::DUPLICATE_NAME"
    INVALID_VOLUME_BACKEND = "VOLUME::INVALID_BACKEND"
    INVALID_MOUNT_PATH = "VOLUME::INVALID_MOUNT_PATH"
    INVALID_SUB_PATH = "VOLUME::INVALID_SUB_PATH"
    INVALID_HOST_PATH = "VOLUME::INVALID_HOST_PATH"
    HOST_PATH_NOT_ALLOWED = "VOLUME::HOST_PATH_NOT_ALLOWED"
    INVALID_PVC_NAME = "VOLUME::INVALID_PVC_NAME"
    UNSUPPORTED_VOLUME_BACKEND = "VOLUME::UNSUPPORTED_BACKEND"
    HOST_PATH_NOT_FOUND = "VOLUME::HOST_PATH_NOT_FOUND"
    HOST_PATH_CREATE_FAILED = "VOLUME::HOST_PATH_CREATE_FAILED"
    PVC_VOLUME_NOT_FOUND = "VOLUME::PVC_NOT_FOUND"
    PVC_VOLUME_INSPECT_FAILED = "VOLUME::PVC_INSPECT_FAILED"
    PVC_SUBPATH_UNSUPPORTED_DRIVER = "VOLUME::PVC_SUBPATH_UNSUPPORTED_DRIVER"
    INVALID_OSSFS_VERSION = "VOLUME::INVALID_OSSFS_VERSION"
    INVALID_OSSFS_ENDPOINT = "VOLUME::INVALID_OSSFS_ENDPOINT"
    INVALID_OSSFS_BUCKET = "VOLUME::INVALID_OSSFS_BUCKET"
    INVALID_OSSFS_OPTION = "VOLUME::INVALID_OSSFS_OPTION"
    INVALID_OSSFS_CREDENTIALS = "VOLUME::INVALID_OSSFS_CREDENTIALS"
    INVALID_OSSFS_MOUNT_ROOT = "VOLUME::INVALID_OSSFS_MOUNT_ROOT"
    OSSFS_PATH_NOT_FOUND = "VOLUME::OSSFS_PATH_NOT_FOUND"
    OSSFS_MOUNT_FAILED = "VOLUME::OSSFS_MOUNT_FAILED"
    OSSFS_UNMOUNT_FAILED = "VOLUME::OSSFS_UNMOUNT_FAILED"

    # Pause/Resume error codes
    INVALID_STATE = "KUBERNETES::INVALID_STATE"


class SnapshotErrorCodes:
    """Canonical error codes for snapshot service operations."""

    INVALID_SOURCE_STATE = "SNAPSHOT::INVALID_SOURCE_STATE"
    RUNTIME_CREATE_FAILED = "SNAPSHOT::RUNTIME_CREATE_FAILED"
    RUNTIME_CREATE_CONFLICT = "SNAPSHOT::RUNTIME_CREATE_CONFLICT"
    RUNTIME_PREFLIGHT_FAILED = "SNAPSHOT::RUNTIME_PREFLIGHT_FAILED"
    UNSUPPORTED_RUNTIME = "SNAPSHOT::UNSUPPORTED_RUNTIME"


__all__ = [
    "RESERVED_LABEL_PREFIX",
    "SANDBOX_ID_LABEL",
    "SANDBOX_TENANT_LABEL",
    "SANDBOX_EXPIRES_AT_LABEL",
    "SANDBOX_CREATED_AT_LABEL",
    "SANDBOX_MANUAL_CLEANUP_LABEL",
    "SANDBOX_PLATFORM_OS_LABEL",
    "SANDBOX_PLATFORM_ARCH_LABEL",
    "SANDBOX_SNAPSHOT_ID_LABEL",
    "SANDBOX_EMBEDDING_PROXY_PORT_LABEL",
    "SANDBOX_HTTP_PORT_LABEL",
    "SANDBOX_OSSFS_MOUNTS_LABEL",
    "SANDBOX_MANAGED_VOLUMES_LABEL",
    "OPEN_SANDBOX_INGRESS_HEADER",
    "OPEN_SANDBOX_EGRESS_AUTH_HEADER",
    "SANDBOX_EGRESS_AUTH_TOKEN_METADATA_KEY",
    "OPEN_SANDBOX_SECURE_ACCESS_HEADER",
    "SANDBOX_SECURE_ACCESS_TOKEN_METADATA_KEY",
    "EGRESS_RULES_ENV",
    "EGRESS_MODE_ENV",
    "OPENSANDBOX_EGRESS_TOKEN",
    "OPENSANDBOX_EGRESS_MITMPROXY_TRANSPARENT",
    "OPENSANDBOX_EGRESS_SANDBOX_ID",
    "OTEL_EXPORTER_OTLP_ENDPOINT",
    "EGRESS_ENV_PREFIX",
    "OPENSANDBOX_EGRESS_MITMPROXY_SSL_INSECURE",
    "OPENSANDBOX_EGRESS_UPSTREAM_PROXY",
    "OPENSANDBOX_EGRESS_UPSTREAM_PROXY_AUTH",
    "OPENSANDBOX_EGRESS_MITMPROXY_UPSTREAM_EXTRA_CA",
    "EGRESS_UPSTREAM_EXTRA_CA_PATH",
    "EGRESS_UPSTREAM_EXTRA_CA_VOLUME_NAME",
    "EGRESS_UPSTREAM_EXTRA_CA_SECRET_KEY",
    "ALLOWED_EGRESS_ENV_VARS",
    "OPENSANDBOX_RUNTIME_VOLUME_NAME",
    "OPENSANDBOX_RUNTIME_MOUNT_PATH",
    "OPENSANDBOX_LIFECYCLE",
    "SandboxErrorCodes",
    "SnapshotErrorCodes",
]