Secure, Fast, and Extensible Sandbox runtime for AI agents.
# 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.
"""Sandbox lifecycle commands: create, list, get, kill, pause, resume, renew, endpoint, health, metrics."""
from __future__ import annotations
import json
from datetime import datetime, timedelta, timezone
from typing import Any
import click
from opensandbox.adapters.converter import MetricsModelConverter
from opensandbox.api.execd.models import Metrics
from opensandbox.models.sandboxes import (
CredentialProxyConfig,
NetworkPolicy,
PlatformSpec,
SandboxFilter,
SandboxImageAuth,
SandboxImageSpec,
SandboxLifecycle,
SandboxMetrics,
SandboxState,
Volume,
)
from pydantic import BaseModel, ValidationError
from opensandbox_cli.client import ClientContext
from opensandbox_cli.utils import (
DURATION,
KEY_VALUE,
handle_errors,
load_json_object,
output_option,
parse_nullable_duration,
prepare_output,
validation_message,
)
@click.group("sandbox", invoke_without_command=True)
@click.pass_context
def sandbox_group(ctx: click.Context) -> None:
"""📦 Manage sandbox lifecycle."""
if ctx.invoked_subcommand is None:
click.echo(ctx.get_help())
_SANDBOX_STATE_CANONICAL = {
state.lower(): state for state in SandboxState.values()
}
def _normalize_sandbox_states(states: tuple[str, ...]) -> list[str] | None:
"""Normalize case-insensitive CLI state filters to SDK canonical values."""
if not states:
return None
normalized: list[str] = []
for state in states:
canonical = _SANDBOX_STATE_CANONICAL.get(state.strip().lower())
if canonical is None:
choices = ", ".join(sorted(SandboxState.values()))
raise click.ClickException(
f"Invalid sandbox state '{state}'. Valid values: {choices}"
)
normalized.append(canonical)
return normalized
@sandbox_group.command("create")
@click.option("--image", "-i", required=False, help="Container image (e.g. python:3.11). Defaults to config value if set.")
@click.option(
"--image-auth-username",
default=None,
help="Registry username for pulling a private image.",
)
@click.option(
"--image-auth-password",
default=None,
help="Registry password or token for pulling a private image.",
)
@click.option(
"--template",
default=None,
help="Template ID (tpl_...) of a Succeeded template to create the sandbox from. Mutually exclusive with --image and --snapshot-id.",
)
@click.option(
"--snapshot-id",
"snapshot_id",
default=None,
help="Snapshot ID to restore the sandbox from. Mutually exclusive with --image and --template.",
)
@click.option(
"--file",
"-f",
"request_file",
type=click.Path(exists=True, dir_okay=False),
default=None,
help=(
"JSON request file in the public CreateSandboxRequest wire format "
"(camelCase keys: image/templateId/snapshotId, timeout in seconds, resourceLimits, "
"networkPolicy, volumes, ...). Mutually exclusive with request-building flags; "
"--skip-health-check, --ready-timeout and -o still apply."
),
)
@click.option(
"--timeout",
"-t",
"timeout_raw",
default=None,
help="Sandbox lifetime (e.g. 10m, 1h), 'none' for manual cleanup, or omit to use defaults.timeout / SDK default TTL.",
)
@click.option("--env", "-e", "envs", multiple=True, type=KEY_VALUE, help="Environment variable (KEY=VALUE). Repeatable.")
@click.option("--metadata", "-m", "metadata_kv", multiple=True, type=KEY_VALUE, help="Metadata (KEY=VALUE). Repeatable.")
@click.option("--extension", "extensions_kv", multiple=True, type=KEY_VALUE, help="Extension parameter (KEY=VALUE). Repeatable.")
@click.option("--resource", "resources_kv", multiple=True, type=KEY_VALUE, help="Resource limit (e.g. cpu=1 memory=2Gi). Repeatable.")
@click.option(
"--entrypoint",
"entrypoint",
multiple=True,
help="Entrypoint argv item. Repeat to build the full entrypoint.",
)
@click.option("--network-policy-file", type=click.Path(exists=True), default=None, help="Network policy JSON file.")
@click.option(
"--credential-proxy",
is_flag=True,
default=False,
help="Enable Credential Vault transparent proxy support. Requires --network-policy-file.",
)
@click.option("--volumes-file", type=click.Path(exists=True), default=None, help="Volumes JSON file (list of volume objects).")
@click.option("--skip-health-check", is_flag=True, default=False, help="Skip waiting for sandbox readiness.")
@click.option("--ready-timeout", type=DURATION, default=None, help="Max wait time for sandbox readiness (e.g. 30s).")
@output_option("table", "json", "yaml")
@click.pass_obj
@handle_errors
def sandbox_create(
obj: ClientContext,
image: str | None,
image_auth_username: str | None,
image_auth_password: str | None,
template: str | None,
snapshot_id: str | None,
request_file: str | None,
timeout_raw: str | None,
envs: tuple[tuple[str, str], ...],
metadata_kv: tuple[tuple[str, str], ...],
extensions_kv: tuple[tuple[str, str], ...],
resources_kv: tuple[tuple[str, str], ...],
entrypoint: tuple[str, ...],
network_policy_file: str | None,
credential_proxy: bool,
volumes_file: str | None,
skip_health_check: bool,
ready_timeout: timedelta | None,
output_format: str | None,
) -> None:
"""Create a new sandbox from an image, a template, a snapshot, or a request file."""
from opensandbox.sync.sandbox import SandboxSync
prepare_output(obj, output_format, allowed=("table", "json", "yaml"), fallback="table")
if request_file is not None:
file_conflicts: list[str] = []
if image is not None:
file_conflicts.append("--image")
if image_auth_username or image_auth_password:
file_conflicts.append("--image-auth-username/--image-auth-password")
if template:
file_conflicts.append("--template")
if snapshot_id:
file_conflicts.append("--snapshot-id")
if timeout_raw is not None:
file_conflicts.append("--timeout")
if envs:
file_conflicts.append("--env")
if metadata_kv:
file_conflicts.append("--metadata")
if extensions_kv:
file_conflicts.append("--extension")
if resources_kv:
file_conflicts.append("--resource")
if entrypoint:
file_conflicts.append("--entrypoint")
if network_policy_file:
file_conflicts.append("--network-policy-file")
if credential_proxy:
file_conflicts.append("--credential-proxy")
if volumes_file:
file_conflicts.append("--volumes-file")
if file_conflicts:
raise click.ClickException(
f"--file cannot be combined with: {', '.join(file_conflicts)}."
)
file_req = _parse_sandbox_request_file(request_file)
if (
file_req["image"] is None
and file_req["template"] is None
and file_req["snapshot_id"] is None
):
raise click.ClickException(
f"Request file '{request_file}' must set one of 'image', 'templateId', or 'snapshotId'."
)
image_spec: SandboxImageSpec | str | None = file_req["image"]
template = file_req["template"]
snapshot_id = file_req["snapshot_id"]
timeout = file_req["timeout"]
timeout_is_set = file_req["timeout_is_set"]
if not timeout_is_set:
default_timeout = obj.resolved_config.get("default_timeout")
if default_timeout:
timeout = parse_nullable_duration(default_timeout)
timeout_is_set = True
env = file_req["env"]
metadata = file_req["metadata"]
extensions = file_req["extensions"]
resource = file_req["resource"]
resource_requests = file_req["resource_requests"]
entrypoint_argv = file_req["entrypoint"]
platform = file_req["platform"]
network_policy = file_req["network_policy"]
credential_proxy_config = file_req["credential_proxy"]
volumes = file_req["volumes"]
secure_access = file_req["secure_access"]
lifecycle = file_req["lifecycle"]
else:
if template and snapshot_id:
raise click.ClickException("--template and --snapshot-id are mutually exclusive.")
if template:
conflicts: list[str] = []
if image is not None:
conflicts.append("--image")
if image_auth_username or image_auth_password:
conflicts.append("--image-auth-username/--image-auth-password")
if envs:
conflicts.append("--env")
if resources_kv:
conflicts.append("--resource")
if entrypoint:
conflicts.append("--entrypoint")
if volumes_file:
conflicts.append("--volumes-file")
if credential_proxy:
conflicts.append("--credential-proxy")
if conflicts:
raise click.ClickException(
"Template mode fixes the workload shape on the server; "
f"{', '.join(conflicts)} cannot be combined with --template."
)
elif snapshot_id:
if image is not None:
raise click.ClickException("--snapshot-id and --image are mutually exclusive.")
if image_auth_username or image_auth_password:
raise click.ClickException(
"--snapshot-id cannot be combined with image auth options."
)
else:
if image is None:
image = obj.resolved_config.get("default_image")
if not image:
raise click.ClickException(
"Sandbox image is required. Pass --image, use --file, or set defaults.image in the CLI config."
)
if bool(image_auth_username) != bool(image_auth_password):
raise click.ClickException(
"Pass both --image-auth-username and --image-auth-password together."
)
if credential_proxy and not network_policy_file:
raise click.ClickException(
"--credential-proxy requires --network-policy-file because Credential Vault injection needs egress policy."
)
timeout_is_set = False
if timeout_raw is not None:
timeout = parse_nullable_duration(timeout_raw)
timeout_is_set = True
else:
timeout = None
default_timeout = obj.resolved_config.get("default_timeout")
if default_timeout:
timeout = parse_nullable_duration(default_timeout)
timeout_is_set = True
image_spec = image
if image_auth_username and image_auth_password:
image_spec = SandboxImageSpec(
image=image,
auth=SandboxImageAuth(
username=image_auth_username,
password=image_auth_password,
),
)
env = dict(envs) if envs else None
metadata = dict(metadata_kv) if metadata_kv else None
extensions = dict(extensions_kv) if extensions_kv else None
resource = dict(resources_kv) if resources_kv else None
resource_requests = None
entrypoint_argv = list(entrypoint) if entrypoint else None
platform = None
network_policy = (
_load_network_policy(network_policy_file) if network_policy_file else None
)
credential_proxy_config = (
CredentialProxyConfig(enabled=True) if credential_proxy else None
)
volumes = None
if volumes_file:
with open(volumes_file) as f:
raw_volumes = json.load(f)
if not isinstance(raw_volumes, list):
raise click.ClickException(
f"Volumes file must contain a JSON array, got {type(raw_volumes).__name__}."
)
volumes = [Volume(**item) for item in raw_volumes]
secure_access = False
lifecycle = None
if template and not timeout_is_set:
if request_file is not None:
raise click.ClickException(
f"'timeout' is required in request file '{request_file}' "
"when 'templateId' is set (in seconds)."
)
raise click.ClickException(
"--timeout is required when creating a sandbox from a template (e.g. --timeout 30m)."
)
with obj.output.spinner("Creating sandbox..."):
if template:
if timeout is None:
if request_file is not None:
raise click.ClickException(
"'timeout': null (manual cleanup) is not supported in template mode."
)
raise click.ClickException(
"--timeout none (manual cleanup) is not supported in template mode."
)
template_kwargs: dict = {}
if ready_timeout is not None:
template_kwargs["ready_timeout"] = ready_timeout
if metadata is not None:
template_kwargs["metadata"] = metadata
if extensions is not None:
template_kwargs["extensions"] = extensions
if network_policy is not None:
template_kwargs["network_policy"] = network_policy
sandbox = SandboxSync.create_from_template(
template,
timeout=timeout,
connection_config=obj.connection_config,
skip_health_check=skip_health_check,
**template_kwargs,
)
else:
kwargs: dict = {
"connection_config": obj.connection_config,
"skip_health_check": skip_health_check,
}
if snapshot_id:
kwargs["snapshot_id"] = snapshot_id
if timeout_is_set:
kwargs["timeout"] = timeout
if ready_timeout is not None:
kwargs["ready_timeout"] = ready_timeout
if env is not None:
kwargs["env"] = env
if metadata is not None:
kwargs["metadata"] = metadata
if extensions is not None:
kwargs["extensions"] = extensions
if resource is not None:
kwargs["resource"] = resource
if resource_requests is not None:
kwargs["resource_requests"] = resource_requests
if entrypoint_argv is not None:
kwargs["entrypoint"] = entrypoint_argv
if platform is not None:
kwargs["platform"] = platform
if network_policy is not None:
kwargs["network_policy"] = network_policy
if credential_proxy_config is not None:
kwargs["credential_proxy"] = credential_proxy_config
if volumes is not None:
kwargs["volumes"] = volumes
if secure_access:
kwargs["secure_access"] = True
if lifecycle is not None:
kwargs["lifecycle"] = lifecycle
sandbox = SandboxSync.create(image_spec, **kwargs)
details: dict[str, Any] = {
"id": sandbox.id,
"status": "created",
"timeout": _describe_create_timeout(timeout_is_set, timeout),
}
if request_file is not None:
details["request_file"] = request_file
if template:
details["template"] = template
elif snapshot_id:
details["snapshot_id"] = snapshot_id
else:
details["image"] = (
image_spec.image if isinstance(image_spec, SandboxImageSpec) else image_spec
)
obj.output.success_panel(
details,
title="Sandbox Created",
)
def _load_network_policy(path: str) -> NetworkPolicy:
with open(path) as f:
return NetworkPolicy(**json.load(f))
_SANDBOX_REQUEST_FILE_FIELDS = (
"image",
"templateId",
"snapshotId",
"platform",
"timeout",
"resourceLimits",
"resourceRequests",
"env",
"metadata",
"lifecycle",
"entrypoint",
"networkPolicy",
"credentialProxy",
"secureAccess",
"volumes",
"extensions",
)
# Fields rejected alongside templateId: template mode fixes the workload shape
# on the server (metadata, extensions, networkPolicy and timeout stay allowed).
_TEMPLATE_MODE_FORBIDDEN_FILE_FIELDS = (
"resourceLimits",
"resourceRequests",
"env",
"entrypoint",
"volumes",
"platform",
"credentialProxy",
"secureAccess",
"lifecycle",
)
def _file_str_dict(data: dict, key: str, path: str) -> dict[str, str] | None:
"""Extract a string-to-string object field from a request file."""
value = data.get(key)
if value is None:
return None
if not isinstance(value, dict) or not all(
isinstance(k, str) and isinstance(v, str) for k, v in value.items()
):
raise click.ClickException(
f"Request file field '{key}' in '{path}' must be an object with string values."
)
return dict(value)
def _file_model(data: dict, key: str, path: str, model_type: type[BaseModel]) -> Any:
"""Extract a model field from a request file, wrapping validation errors."""
value = data.get(key)
if value is None:
return None
if not isinstance(value, dict):
raise click.ClickException(
f"Request file field '{key}' in '{path}' must be an object."
)
try:
return model_type.model_validate(value)
except ValidationError as exc:
raise click.ClickException(
f"Invalid '{key}' in request file '{path}': {validation_message(exc)}"
) from exc
def _file_image_spec(value: object, path: str) -> SandboxImageSpec | str:
"""Parse the request file 'image' field (string or {uri, auth} object)."""
if isinstance(value, str):
if not value.strip():
raise click.ClickException(
f"Request file field 'image' in '{path}' must not be blank."
)
return value
if isinstance(value, dict):
uri = value.get("uri")
if not isinstance(uri, str) or not uri.strip():
raise click.ClickException(
f"Request file field 'image' in '{path}' must be a string or an object "
"with a non-empty 'uri'."
)
auth = value.get("auth")
if auth is None:
return uri
if not isinstance(auth, dict):
raise click.ClickException(
f"Request file field 'image.auth' in '{path}' must be an object."
)
try:
return SandboxImageSpec(image=uri, auth=SandboxImageAuth(**auth))
except ValidationError as exc:
raise click.ClickException(
f"Invalid 'image.auth' in request file '{path}': {validation_message(exc)}"
) from exc
raise click.ClickException(
f"Request file field 'image' in '{path}' must be a string or an object with 'uri'."
)
def _parse_sandbox_request_file(path: str) -> dict[str, Any]:
"""Parse a CreateSandboxRequest wire-format JSON file into create variables."""
data = load_json_object(path)
unknown = sorted(set(data) - set(_SANDBOX_REQUEST_FILE_FIELDS))
if unknown:
raise click.ClickException(
f"Request file '{path}' has unsupported fields: {', '.join(unknown)}. "
f"Supported fields: {', '.join(_SANDBOX_REQUEST_FILE_FIELDS)}."
)
image = data.get("image")
template_id = data.get("templateId")
snapshot_id = data.get("snapshotId")
sources = [
name
for name, value in (
("image", image),
("templateId", template_id),
("snapshotId", snapshot_id),
)
if value is not None
]
if len(sources) > 1:
raise click.ClickException(
f"Request file '{path}' must set only one of 'image', 'templateId', "
f"'snapshotId'; got {', '.join(sources)}."
)
req: dict[str, Any] = {
"image": None,
"template": None,
"snapshot_id": None,
"timeout": None,
"timeout_is_set": False,
"env": None,
"metadata": None,
"extensions": None,
"resource": None,
"resource_requests": None,
"entrypoint": None,
"platform": None,
"network_policy": None,
"credential_proxy": None,
"volumes": None,
"secure_access": False,
"lifecycle": None,
}
if image is not None:
req["image"] = _file_image_spec(image, path)
if template_id is not None:
if not isinstance(template_id, str) or not template_id.strip():
raise click.ClickException(
f"Request file field 'templateId' in '{path}' must be a non-empty string."
)
req["template"] = template_id
if snapshot_id is not None:
if not isinstance(snapshot_id, str) or not snapshot_id.strip():
raise click.ClickException(
f"Request file field 'snapshotId' in '{path}' must be a non-empty string."
)
req["snapshot_id"] = snapshot_id
if "timeout" in data:
raw_timeout = data["timeout"]
if raw_timeout is None:
req["timeout"] = None
req["timeout_is_set"] = True
elif isinstance(raw_timeout, int) and not isinstance(raw_timeout, bool):
if raw_timeout <= 0:
raise click.ClickException(
f"Request file field 'timeout' in '{path}' must be a positive integer "
"of seconds, or null for manual cleanup."
)
req["timeout"] = timedelta(seconds=raw_timeout)
req["timeout_is_set"] = True
else:
raise click.ClickException(
f"Request file field 'timeout' in '{path}' must be a positive integer of "
"seconds, or null for manual cleanup."
)
if req["template"] is not None:
def _is_set(name: str) -> bool:
# Mirror the server: explicit `secureAccess: false` is the documented
# default and stays allowed alongside templateId.
if name == "secureAccess":
return data.get(name) is True
return data.get(name) is not None
fixed_fields = [
f"'{name}'"
for name in _TEMPLATE_MODE_FORBIDDEN_FILE_FIELDS
if _is_set(name)
]
if fixed_fields:
raise click.ClickException(
"Template mode fixes the workload shape on the server; "
f"request file cannot combine 'templateId' with {', '.join(fixed_fields)}."
)
req["env"] = _file_str_dict(data, "env", path)
req["metadata"] = _file_str_dict(data, "metadata", path)
req["extensions"] = _file_str_dict(data, "extensions", path)
req["resource"] = _file_str_dict(data, "resourceLimits", path)
req["resource_requests"] = _file_str_dict(data, "resourceRequests", path)
entrypoint = data.get("entrypoint")
if entrypoint is not None:
if (
not isinstance(entrypoint, list)
or not entrypoint
or not all(isinstance(item, str) for item in entrypoint)
):
raise click.ClickException(
f"Request file field 'entrypoint' in '{path}' must be a non-empty array "
"of strings."
)
req["entrypoint"] = list(entrypoint)
secure_access = data.get("secureAccess")
if secure_access is not None:
if not isinstance(secure_access, bool):
raise click.ClickException(
f"Request file field 'secureAccess' in '{path}' must be a boolean."
)
req["secure_access"] = secure_access
req["platform"] = _file_model(data, "platform", path, PlatformSpec)
req["network_policy"] = _file_model(data, "networkPolicy", path, NetworkPolicy)
req["lifecycle"] = _file_model(data, "lifecycle", path, SandboxLifecycle)
credential_proxy = data.get("credentialProxy")
if credential_proxy is not None:
if isinstance(credential_proxy, bool):
req["credential_proxy"] = CredentialProxyConfig(enabled=credential_proxy)
elif isinstance(credential_proxy, dict):
try:
req["credential_proxy"] = CredentialProxyConfig.model_validate(
credential_proxy
)
except ValidationError as exc:
raise click.ClickException(
f"Invalid 'credentialProxy' in request file '{path}': "
f"{validation_message(exc)}"
) from exc
else:
raise click.ClickException(
f"Request file field 'credentialProxy' in '{path}' must be a boolean "
"or an object."
)
if (
req["credential_proxy"] is not None
and req["credential_proxy"].enabled
and req["network_policy"] is None
):
raise click.ClickException(
f"Request file field 'credentialProxy' in '{path}' requires 'networkPolicy' "
"because Credential Vault injection needs egress policy."
)
volumes = data.get("volumes")
if volumes is not None:
if not isinstance(volumes, list):
raise click.ClickException(
f"Request file field 'volumes' in '{path}' must be an array."
)
parsed_volumes: list[Volume] = []
for item in volumes:
if not isinstance(item, dict):
raise click.ClickException(
f"Request file field 'volumes' in '{path}' must contain volume objects."
)
try:
parsed_volumes.append(Volume.model_validate(item))
except ValidationError as exc:
raise click.ClickException(
f"Invalid 'volumes' entry in request file '{path}': "
f"{validation_message(exc)}"
) from exc
req["volumes"] = parsed_volumes
return req
@sandbox_group.command("list")
@click.option("--state", "-s", "states", multiple=True, help="Filter by state (Pending, Running, Paused, ...). Repeatable.")
@click.option("--metadata", "-m", "metadata_kv", multiple=True, type=KEY_VALUE, help="Metadata filter (KEY=VALUE). Repeatable.")
@click.option("--page", type=click.IntRange(min=1), default=None, help="Page number (1-indexed).")
@click.option("--page-size", type=click.IntRange(min=1), default=None, help="Items per page.")
@output_option("table", "json", "yaml")
@click.pass_obj
@handle_errors
def sandbox_list(
obj: ClientContext,
states: tuple[str, ...],
metadata_kv: tuple[tuple[str, str], ...],
page: int | None,
page_size: int | None,
output_format: str | None,
) -> None:
"""List sandboxes."""
prepare_output(obj, output_format, allowed=("table", "json", "yaml"), fallback="table")
mgr = obj.get_manager()
filt = SandboxFilter(
states=_normalize_sandbox_states(states),
metadata=dict(metadata_kv) if metadata_kv else None,
page=page,
page_size=page_size,
)
with obj.output.spinner("Fetching sandboxes..."):
result = mgr.list_sandbox_infos(filt)
if not result.sandbox_infos:
if obj.output.fmt in ("json", "yaml"):
obj.output.print_dict(
{
"items": [],
"pagination": result.pagination.model_dump(mode="json"),
},
title="Sandboxes",
)
else:
obj.output.info("No sandboxes found.")
return
raw_rows = [info.model_dump(mode="json") for info in result.sandbox_infos]
if obj.output.fmt in ("json", "yaml"):
obj.output.print_dict(
{
"items": raw_rows,
"pagination": result.pagination.model_dump(mode="json"),
},
title="Sandboxes",
)
return
rows = []
for d in raw_rows:
flat = dict(d)
status_val = flat.get("status")
if isinstance(status_val, dict):
flat["status"] = status_val.get("state", str(status_val))
image_val = flat.get("image")
if isinstance(image_val, dict):
flat["image"] = image_val.get("image", str(image_val))
rows.append(flat)
obj.output.print_rows(
rows,
columns=["id", "status", "image", "created_at", "expires_at"],
title="Sandboxes",
)
@sandbox_group.command("get")
@click.argument("sandbox_id")
@output_option("table", "json", "yaml")
@click.pass_obj
@handle_errors
def sandbox_get(obj: ClientContext, sandbox_id: str, output_format: str | None) -> None:
"""Get sandbox details."""
prepare_output(obj, output_format, allowed=("table", "json", "yaml"), fallback="table")
mgr = obj.get_manager()
info = mgr.get_sandbox_info(sandbox_id)
d = info.model_dump(mode="json")
if obj.output.fmt in ("json", "yaml"):
obj.output.print_dict(d, title="Sandbox Info")
return
status_val = d.get("status")
if isinstance(status_val, dict):
d["status"] = status_val.get("state", str(status_val))
if status_val.get("reason"):
d["status_reason"] = status_val["reason"]
if status_val.get("message"):
d["status_message"] = status_val["message"]
image_val = d.get("image")
if isinstance(image_val, dict):
d["image"] = image_val.get("image", str(image_val))
obj.output.print_dict(d, title="Sandbox Info")
@sandbox_group.command("kill")
@click.argument("sandbox_ids", nargs=-1, required=True)
@output_option("table", "json", "yaml")
@click.pass_obj
@handle_errors
def sandbox_kill(
obj: ClientContext, sandbox_ids: tuple[str, ...], output_format: str | None
) -> None:
"""Request deletion of one or more sandboxes; cleanup may continue."""
prepare_output(obj, output_format, allowed=("table", "json", "yaml"), fallback="table")
mgr = obj.get_manager()
rows: list[dict[str, str]] = []
for sid in sandbox_ids:
with obj.output.spinner(f"Killing sandbox {sid}..."):
mgr.kill_sandbox(sid)
rows.append({"sandbox_id": sid, "status": "deletion_requested"})
obj.output.print_rows(rows, columns=["sandbox_id", "status"], title="Sandboxes")
@sandbox_group.command("pause")
@click.argument("sandbox_id")
@output_option("table", "json", "yaml")
@click.pass_obj
@handle_errors
def sandbox_pause(obj: ClientContext, sandbox_id: str, output_format: str | None) -> None:
"""Pause a running sandbox."""
prepare_output(obj, output_format, allowed=("table", "json", "yaml"), fallback="table")
mgr = obj.get_manager()
with obj.output.spinner("Pausing sandbox..."):
mgr.pause_sandbox(sandbox_id)
obj.output.success(f"Pause request accepted: {sandbox_id}")
@sandbox_group.command("resume")
@click.argument("sandbox_id")
@click.option("--skip-health-check", is_flag=True, default=False, help="Skip waiting for sandbox readiness after resume.")
@click.option("--resume-timeout", type=DURATION, default=None, help="Max wait time for sandbox readiness after resume (e.g. 30s).")
@output_option("table", "json", "yaml")
@click.pass_obj
@handle_errors
def sandbox_resume(
obj: ClientContext,
sandbox_id: str,
skip_health_check: bool,
resume_timeout: timedelta | None,
output_format: str | None,
) -> None:
"""Resume a paused sandbox."""
from opensandbox.sync.sandbox import SandboxSync
prepare_output(obj, output_format, allowed=("table", "json", "yaml"), fallback="table")
sandbox = None
try:
kwargs = {
"connection_config": obj.connection_config,
"skip_health_check": skip_health_check,
}
if resume_timeout is not None:
kwargs["resume_timeout"] = resume_timeout
with obj.output.spinner("Resuming sandbox..."):
sandbox = SandboxSync.resume(sandbox_id, **kwargs)
obj.output.success(f"Sandbox resumed: {sandbox_id}")
finally:
if sandbox is not None:
sandbox.close()
@sandbox_group.command("renew")
@click.argument("sandbox_id")
@click.option("--timeout", "-t", required=True, type=DURATION, help="New TTL duration (e.g. 30m, 2h).")
@output_option("table", "json", "yaml")
@click.pass_obj
@handle_errors
def sandbox_renew(
obj: ClientContext,
sandbox_id: str,
timeout: timedelta,
output_format: str | None,
) -> None:
"""Renew sandbox expiration."""
prepare_output(obj, output_format, allowed=("table", "json", "yaml"), fallback="table")
mgr = obj.get_manager()
with obj.output.spinner("Renewing sandbox..."):
resp = mgr.renew_sandbox(sandbox_id, timeout)
obj.output.success_panel(
{"sandbox_id": sandbox_id, "expires_at": str(resp.expires_at)},
title="Sandbox Renewed",
)
@sandbox_group.command("endpoint")
@click.argument("sandbox_id")
@click.option("--port", "-p", required=True, type=click.IntRange(min=1, max=65535), help="Port number.")
@output_option("table", "json", "yaml")
@click.pass_obj
@handle_errors
def sandbox_endpoint(
obj: ClientContext, sandbox_id: str, port: int, output_format: str | None
) -> None:
"""Get the public endpoint for a sandbox port."""
prepare_output(obj, output_format, allowed=("table", "json", "yaml"), fallback="table")
sandbox = obj.connect_sandbox(sandbox_id)
try:
ep = sandbox.get_endpoint(port)
obj.output.print_model(ep, title="Sandbox Endpoint")
finally:
sandbox.close()
@sandbox_group.command("health")
@click.argument("sandbox_id")
@output_option("table", "json", "yaml")
@click.pass_obj
@handle_errors
def sandbox_health(
obj: ClientContext, sandbox_id: str, output_format: str | None
) -> None:
"""Check sandbox health."""
prepare_output(obj, output_format, allowed=("table", "json", "yaml"), fallback="table")
sandbox = obj.connect_sandbox(sandbox_id)
try:
healthy = sandbox.is_healthy()
if obj.output.fmt == "table":
if healthy:
obj.output.success(f"Sandbox {sandbox_id} is healthy")
else:
obj.output.error(f"Sandbox {sandbox_id} is unhealthy")
else:
obj.output.print_dict(
{"sandbox_id": sandbox_id, "healthy": healthy},
title="Health Check",
)
finally:
sandbox.close()
@sandbox_group.command("metrics")
@click.argument("sandbox_id")
@click.option("--watch", is_flag=True, default=False, help="Stream metrics updates in real time.")
@output_option("table", "json", "yaml", "raw")
@click.pass_obj
@handle_errors
def sandbox_metrics(
obj: ClientContext,
sandbox_id: str,
watch: bool,
output_format: str | None,
) -> None:
"""Get sandbox resource metrics."""
fallback = "raw" if watch else "table"
prepare_output(
obj, output_format, allowed=("table", "json", "yaml", "raw"), fallback=fallback
)
sandbox = obj.connect_sandbox(sandbox_id)
try:
if watch:
_watch_sandbox_metrics(obj, sandbox)
return
m = sandbox.get_metrics()
obj.output.print_model(m, title="Sandbox Metrics")
finally:
sandbox.close()
def _watch_sandbox_metrics(obj: ClientContext, sandbox) -> None: # type: ignore[no-untyped-def]
"""Stream sandbox metrics from the execd SSE endpoint."""
client = getattr(sandbox.metrics, "_httpx_client", None)
if client is None:
raise click.ClickException("Streaming metrics are unavailable for this sandbox connection.")
headers = {"Accept": "text/event-stream"}
try:
with client.stream("GET", "/metrics/watch", headers=headers) as response:
response.raise_for_status()
for line in response.iter_lines():
metric, warning = _parse_metric_stream_line(line)
if warning:
obj.output.warning(warning)
continue
if metric is None:
continue
_render_stream_metric(obj, metric)
except KeyboardInterrupt:
return
def _parse_metric_stream_line(line: str) -> tuple[SandboxMetrics | None, str | None]:
"""Parse one line from the metrics SSE stream."""
stripped = line.strip()
if not stripped or stripped.startswith((":","event:", "id:", "retry:")):
return None, None
payload = stripped[5:].strip() if stripped.startswith("data:") else stripped
if not payload:
return None, None
decoded: Any = json.loads(payload)
if isinstance(decoded, dict) and decoded.get("error"):
return None, f"Metrics stream error: {decoded['error']}"
if isinstance(decoded, dict) and "cpu_used_pct" in decoded:
return MetricsModelConverter.to_sandbox_metrics(Metrics.from_dict(decoded)), None
return SandboxMetrics.model_validate(decoded), None
def _describe_create_timeout(
timeout_is_set: bool, timeout: timedelta | None
) -> str:
"""Describe the sandbox timeout mode shown in create output."""
if not timeout_is_set:
return "sdk-default"
if timeout is None:
return "manual-cleanup"
return str(timeout)
def _render_stream_metric(obj: ClientContext, metric: SandboxMetrics) -> None:
"""Render one streaming metrics sample."""
if obj.output.fmt in ("table", "raw"):
timestamp = datetime.fromtimestamp(metric.timestamp / 1000, tz=timezone.utc).isoformat()
click.echo(
" ".join(
[
f"[{timestamp}]",
f"cpu={metric.cpu_used_percentage:.2f}%",
f"cores={metric.cpu_count:g}",
f"mem={metric.memory_used_in_mib:.2f}/{metric.memory_total_in_mib:.2f}MiB",
]
)
)
return
if obj.output.fmt == "json":
click.echo(json.dumps(metric.model_dump(mode="json"), default=str))
return
obj.output.print_model(metric)