Skip to content

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

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

"""Template commands: create, get, list, delete."""

from __future__ import annotations

from typing import Literal, cast

import click
from opensandbox.models.templates import (
    CreateTemplateRequest,
    TemplateFilter,
    TemplateReadiness,
)
from pydantic import ValidationError

from opensandbox_cli.utils import (
    KEY_VALUE,
    handle_errors,
    load_json_object,
    output_option,
    prepare_output,
    validation_message,
)


@click.group("template", invoke_without_command=True)
@click.pass_context
def template_group(ctx: click.Context) -> None:
    """🏗 Manage sandbox templates (golden-image builds)."""
    if ctx.invoked_subcommand is None:
        click.echo(ctx.get_help())


@template_group.command("create")
@click.option(
    "--image",
    "-i",
    default=None,
    help="Source OCI image reference the golden image is built from. Required unless --file is used.",
)
@click.option(
    "--publish",
    "-p",
    default=None,
    help="Publish target: s3://bucket/publish (native) or oci://registry/repository (overlaybd, no tag or digest). Required unless --file is used.",
)
@click.option(
    "--file",
    "-f",
    "request_file",
    type=click.Path(exists=True, dir_okay=False),
    default=None,
    help=(
        "JSON request file in the public CreateTemplateRequest wire format "
        "(camelCase keys: image, publish, resourceLimits, entrypoint, env, metadata, "
        "format, readiness.probe, readiness.warmupSeconds). Mutually exclusive with "
        "request-building flags; -o still applies."
    ),
)
@click.option(
    "--resource",
    "resources_kv",
    multiple=True,
    type=KEY_VALUE,
    help="Guest machine sizing (e.g. cpu=1 memory=512Mi disk=2Gi). Repeatable.",
)
@click.option(
    "--entrypoint",
    "entrypoint",
    multiple=True,
    help="Guest business command argv item. Repeat to build the full entrypoint.",
)
@click.option(
    "--env",
    "-e",
    "envs",
    multiple=True,
    type=KEY_VALUE,
    help="Environment variable baked into the golden image (KEY=VALUE). Repeatable.",
)
@click.option("--metadata", "-m", "metadata_kv", multiple=True, type=KEY_VALUE, help="Metadata (KEY=VALUE). Repeatable.")
@click.option(
    "--format",
    "image_format",
    type=click.Choice(["native", "overlaybd"]),
    default=None,
    help="Storage encoding of the produced snapshots. Defaults to the server default (overlaybd).",
)
@click.option(
    "--readiness-probe",
    default=None,
    help="Build readiness probe checked first (e.g. tcp://127.0.0.1:44772 or cmd://<command>).",
)
@click.option(
    "--warmup-seconds",
    type=click.IntRange(min=0),
    default=None,
    help="Fallback warmup window in seconds used when no probe is set.",
)
@output_option("table", "json", "yaml")
@click.pass_obj
@handle_errors
def template_create(
    obj,
    image: str | None,
    publish: str | None,
    resources_kv: tuple[tuple[str, str], ...],
    entrypoint: tuple[str, ...],
    envs: tuple[tuple[str, str], ...],
    metadata_kv: tuple[tuple[str, str], ...],
    image_format: str | None,
    readiness_probe: str | None,
    warmup_seconds: int | None,
    request_file: str | None,
    output_format: str | None,
) -> None:
    """Create a template and start its asynchronous golden-image build."""
    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 publish is not None:
            file_conflicts.append("--publish")
        if resources_kv:
            file_conflicts.append("--resource")
        if entrypoint:
            file_conflicts.append("--entrypoint")
        if envs:
            file_conflicts.append("--env")
        if metadata_kv:
            file_conflicts.append("--metadata")
        if image_format is not None:
            file_conflicts.append("--format")
        if readiness_probe is not None:
            file_conflicts.append("--readiness-probe")
        if warmup_seconds is not None:
            file_conflicts.append("--warmup-seconds")
        if file_conflicts:
            raise click.ClickException(
                f"--file cannot be combined with: {', '.join(file_conflicts)}."
            )
        data = load_json_object(request_file)
        known_fields = set(CreateTemplateRequest.model_fields) | {
            field.alias
            for field in CreateTemplateRequest.model_fields.values()
            if field.alias
        }
        unknown = sorted(set(data) - known_fields)
        if unknown:
            raise click.ClickException(
                f"Request file '{request_file}' has unsupported fields: "
                f"{', '.join(unknown)}."
            )
        try:
            request = CreateTemplateRequest.model_validate(data)
        except ValidationError as exc:
            raise click.ClickException(
                f"Invalid request file '{request_file}': {validation_message(exc)}"
            ) from exc
    else:
        if image is None or publish is None:
            missing = [
                name
                for name, value in (("--image", image), ("--publish", publish))
                if not value
            ]
            raise click.ClickException(
                f"Missing required options: {', '.join(missing)} (or pass --file)."
            )
        readiness = None
        if readiness_probe is not None or warmup_seconds is not None:
            readiness = TemplateReadiness(probe=readiness_probe, warmupSeconds=warmup_seconds)

        request = CreateTemplateRequest(
            image=image,
            publish=publish,
            resourceLimits=dict(resources_kv) if resources_kv else None,
            entrypoint=list(entrypoint) if entrypoint else None,
            env=dict(envs) if envs else None,
            metadata=dict(metadata_kv) if metadata_kv else None,
            format=cast(Literal["native", "overlaybd"] | None, image_format),
            readiness=readiness,
        )
    mgr = obj.get_manager()

    with obj.output.spinner("Creating template..."):
        info = mgr.create_template(request)
    details = {
        "template_id": info.template_id,
        "image": info.image,
        "status": info.status.phase,
    }
    if request_file is not None:
        details["request_file"] = request_file
    obj.output.success_panel(
        details,
        title="Template Created",
    )


@template_group.command("get")
@click.argument("template_id")
@output_option("table", "json", "yaml")
@click.pass_obj
@handle_errors
def template_get(obj, template_id: str, output_format: str | None) -> None:
    """Get template details including its latest build status."""
    prepare_output(obj, output_format, allowed=("table", "json", "yaml"), fallback="table")
    mgr = obj.get_manager()
    with obj.output.spinner("Fetching template..."):
        info = mgr.get_template(template_id)
    d = info.model_dump(mode="json")

    if obj.output.fmt in ("json", "yaml"):
        obj.output.print_dict(d, title="Template Info")
        return

    status_val = d.get("status")
    if isinstance(status_val, dict):
        d["status"] = status_val.get("phase", str(status_val))
        if status_val.get("message"):
            d["status_message"] = status_val["message"]
    readiness_val = d.get("readiness")
    if isinstance(readiness_val, dict):
        parts = []
        if readiness_val.get("probe"):
            parts.append(readiness_val["probe"])
        if readiness_val.get("warmup_seconds") is not None:
            parts.append(f"warmup={readiness_val['warmup_seconds']}s")
        d["readiness"] = " ".join(parts) if parts else None
    obj.output.print_dict(d, title="Template Info")


@template_group.command("list")
@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 template_list(
    obj,
    metadata_kv: tuple[tuple[str, str], ...],
    page: int | None,
    page_size: int | None,
    output_format: str | None,
) -> None:
    """List templates."""
    prepare_output(obj, output_format, allowed=("table", "json", "yaml"), fallback="table")
    mgr = obj.get_manager()
    filt = TemplateFilter(
        metadata=dict(metadata_kv) if metadata_kv else None,
        page=page,
        pageSize=page_size,
    )
    with obj.output.spinner("Fetching templates..."):
        result = mgr.list_templates(filt)
    if not result.template_infos:
        if obj.output.fmt in ("json", "yaml"):
            obj.output.print_dict(
                {
                    "items": [],
                    "pagination": result.pagination.model_dump(mode="json"),
                },
                title="Templates",
            )
        else:
            obj.output.info("No templates found.")
        return

    raw_rows = [info.model_dump(mode="json") for info in result.template_infos]

    if obj.output.fmt in ("json", "yaml"):
        obj.output.print_dict(
            {
                "items": raw_rows,
                "pagination": result.pagination.model_dump(mode="json"),
            },
            title="Templates",
        )
        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("phase", str(status_val))
        rows.append(flat)

    obj.output.print_rows(
        rows,
        columns=["template_id", "status", "image", "format", "created_at", "updated_at"],
        title="Templates",
    )


@template_group.command("delete")
@click.argument("template_id")
@output_option("table", "json", "yaml")
@click.pass_obj
@handle_errors
def template_delete(obj, template_id: str, output_format: str | None) -> None:
    """Delete a template by ID. Running sandboxes are unaffected."""
    prepare_output(obj, output_format, allowed=("table", "json", "yaml"), fallback="table")
    mgr = obj.get_manager()
    with obj.output.spinner(f"Deleting template {template_id}..."):
        mgr.delete_template(template_id)
    obj.output.success(f"Template deleted: {template_id}")