Skip to content

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

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

"""Root Click group with global options."""

from __future__ import annotations

import sys
from pathlib import Path

import click
from rich.console import Console

from opensandbox_cli import __version__
from opensandbox_cli.client import ClientContext
from opensandbox_cli.commands.command import command_group
from opensandbox_cli.commands.config_cmd import config_group
from opensandbox_cli.commands.credential_vault import credential_vault_group
from opensandbox_cli.commands.devops import devops_group
from opensandbox_cli.commands.diagnostics import diagnostics_group
from opensandbox_cli.commands.egress import egress_group
from opensandbox_cli.commands.file import file_group
from opensandbox_cli.commands.sandbox import sandbox_group
from opensandbox_cli.commands.skills import skills_group
from opensandbox_cli.commands.snapshot import snapshot_group
from opensandbox_cli.commands.template import template_group
from opensandbox_cli.commands.terminal import terminal
from opensandbox_cli.config import resolve_config

BANNER = r"""[bold cyan]
   ____                   _____                 _ _
  / __ \                 / ____|               | | |
 | |  | |_ __   ___ _ _| (___   __ _ _ __   __| | |__   _____  __
 | |  | | '_ \ / _ \ '_ \___ \ / _` | '_ \ / _` | '_ \ / _ \ \/ /
 | |__| | |_) |  __/ | | |___) | (_| | | | | (_| | |_) | (_) >  <
  \____/| .__/ \___|_| |_|____/ \__,_|_| |_|\__,_|_.__/ \___/_/\_\
        | |
        |_|[/]  [dim]v{version}[/]
"""


# A representative icon: any encoding that cannot render it would raise on output.
_OUTPUT_PROBE = "\u2705"


def _configure_output_streams() -> None:
    """Keep CLI output writable when the active encoding cannot represent it.

    Click and Rich print emoji and box-drawing characters. On a legacy Windows
    code page (cp936, cp1252, ...) or a POSIX ``C`` locale writing them raises
    ``UnicodeEncodeError``, which aborts the command - even after the work is
    done - so streams whose encoding cannot represent that output escape the
    characters instead of raising.

    Escaping (``backslashreplace``) keeps payload writes - raw command and
    file data, machine-readable output - recoverable; ``errors="replace"``
    would silently corrupt them into ``?``. CPython uses the same handler for
    Windows stderr.
    """
    for stream in (sys.stdout, sys.stderr):
        reconfigure = getattr(stream, "reconfigure", None)
        encoding = getattr(stream, "encoding", None)
        if reconfigure is None or encoding is None:
            continue
        try:
            _OUTPUT_PROBE.encode(encoding)
        except (LookupError, UnicodeEncodeError):
            try:
                reconfigure(errors="backslashreplace")
            except (OSError, ValueError):  # pragma: no cover - detached stream
                pass


class BannerGroup(click.Group):
    """Custom Click group that shows a banner before help text."""

    def parse_args(self, ctx: click.Context, args: list[str]) -> list[str]:
        """Configure output streams before Click renders help or runs a command."""
        _configure_output_streams()
        return super().parse_args(ctx, args)

    def format_help(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
        console = Console(stderr=False)
        console.print(BANNER.format(version=__version__))
        super().format_help(ctx, formatter)


@click.group(cls=BannerGroup, context_settings={"help_option_names": ["-h", "--help"]})
@click.option("--api-key", envvar="OPEN_SANDBOX_API_KEY", default=None, help="API key for authentication.")
@click.option("--domain", envvar="OPEN_SANDBOX_DOMAIN", default=None, help="API server domain (e.g. localhost:8080).")
@click.option("--protocol", type=click.Choice(["http", "https"]), default=None, help="Protocol (http/https).")
@click.option("--request-timeout", type=int, default=None, help="Request timeout in seconds.")
@click.option(
    "--use-server-proxy/--no-use-server-proxy",
    default=None,
    help="Route execd and endpoint traffic through the sandbox server proxy.",
)
@click.option("--config", "config_path", type=click.Path(exists=False, path_type=Path), default=None, help="Config file path.")
@click.option("-v", "--verbose", is_flag=True, default=False, help="Enable verbose/debug output.")
@click.option("--no-color", is_flag=True, default=False, help="Disable colored output.")
@click.version_option(version=__version__, prog_name="opensandbox")
@click.pass_context
def cli(
    ctx: click.Context,
    api_key: str | None,
    domain: str | None,
    protocol: str | None,
    request_timeout: int | None,
    use_server_proxy: bool | None,
    config_path: Path | None,
    verbose: bool,
    no_color: bool,
) -> None:
    """OpenSandbox CLI — manage sandboxes from your terminal."""
    if verbose:
        import logging

        logging.basicConfig(level=logging.DEBUG)

    cli_overrides = {
        "api_key": api_key,
        "domain": domain,
        "protocol": protocol,
        "request_timeout": request_timeout,
        "use_server_proxy": use_server_proxy,
    }

    if ctx.invoked_subcommand == "config":
        resolved = {
            "api_key": api_key,
            "domain": domain,
            "protocol": protocol or "http",
            "request_timeout": request_timeout or 30,
            "use_server_proxy": use_server_proxy if use_server_proxy is not None else False,
            "color": True,
            "default_image": None,
            "default_timeout": None,
        }
    else:
        resolved = resolve_config(
            cli_api_key=api_key,
            cli_domain=domain,
            cli_protocol=protocol,
            cli_timeout=request_timeout,
            cli_use_server_proxy=use_server_proxy,
            config_path=config_path,
        )
    resolved["color"] = not no_color and resolved.get("color", True)

    effective_config_path = config_path or Path.home() / ".opensandbox" / "config.toml"
    ctx.obj = ClientContext(
        resolved_config=resolved,
        config_path=effective_config_path,
        cli_overrides=cli_overrides,
    )
    ctx.call_on_close(lambda: ctx.obj.close())


cli.add_command(sandbox_group)
cli.add_command(template_group)
cli.add_command(snapshot_group)
cli.add_command(command_group)
cli.add_command(terminal)
cli.add_command(file_group)
cli.add_command(egress_group)
cli.add_command(credential_vault_group)
cli.add_command(config_group)
cli.add_command(diagnostics_group)
cli.add_command(devops_group)
cli.add_command(skills_group)