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.
"""Stable sandbox diagnostics commands backed by the Python SDK."""
from __future__ import annotations
import click
from opensandbox.models.diagnostics import DiagnosticContent
from opensandbox_cli.client import ClientContext
from opensandbox_cli.utils import handle_errors, output_option, prepare_output
def render_diagnostic_content(
obj: ClientContext,
content: DiagnosticContent,
output_format: str | None,
*,
title: str,
) -> None:
"""Render diagnostics descriptor or raw diagnostic payload."""
output = prepare_output(
obj,
output_format,
allowed=("table", "json", "yaml", "raw"),
fallback="raw",
)
if output.fmt == "raw":
if content.truncated:
click.echo("Warning: diagnostic content was truncated.", err=True)
for warning in content.warnings or []:
click.echo(f"Warning: {warning}", err=True)
if content.delivery == "inline":
click.echo(content.content or "")
return
if content.content_url:
click.echo(content.content_url)
return
raise click.ClickException(
"Diagnostic response did not include inline content or a content URL."
)
output.print_dict(content.model_dump(mode="json"), title=title)
@click.group("diagnostics", invoke_without_command=True)
@click.pass_context
def diagnostics_group(ctx: click.Context) -> None:
"""Stable sandbox diagnostics backed by the OpenSandbox SDK."""
if ctx.invoked_subcommand is None:
click.echo(ctx.get_help())
@diagnostics_group.command("context")
@click.argument("sandbox_id")
@output_option("table", "json", "yaml")
@click.pass_obj
@handle_errors
def diagnostics_context(
obj: ClientContext,
sandbox_id: str,
output_format: str | None,
) -> None:
"""Identify the sandbox backend and its diagnostic identifiers."""
context = obj.get_manager().get_diagnostic_context(sandbox_id)
output = prepare_output(
obj, output_format, allowed=("table", "json", "yaml"), fallback="table"
)
output.print_dict(context.model_dump(mode="json"), title="Diagnostic Context")
@diagnostics_group.command("logs")
@click.argument("sandbox_id")
@click.option(
"--scope",
"-s",
required=True,
help=(
"Diagnostic log scope. Built-in server scopes: container and all; "
"other scopes are server-defined."
),
)
@output_option(
"table",
"json",
"yaml",
"raw",
help_text="Output format. raw prints inline text, or the content URL for URL-delivered diagnostics.",
)
@click.pass_obj
@handle_errors
def diagnostics_logs(
obj: ClientContext,
sandbox_id: str,
scope: str,
output_format: str | None,
) -> None:
"""Retrieve diagnostic logs for a sandbox."""
content = obj.get_manager().get_diagnostic_logs(sandbox_id, scope=scope)
render_diagnostic_content(obj, content, output_format, title="Diagnostic Logs")
@diagnostics_group.command("events")
@click.argument("sandbox_id")
@click.option(
"--scope",
"-s",
required=True,
help=(
"Diagnostic event scope. Built-in server scopes: runtime and all; "
"other scopes are server-defined."
),
)
@output_option(
"table",
"json",
"yaml",
"raw",
help_text="Output format. raw prints inline text, or the content URL for URL-delivered diagnostics.",
)
@click.pass_obj
@handle_errors
def diagnostics_events(
obj: ClientContext,
sandbox_id: str,
scope: str,
output_format: str | None,
) -> None:
"""Retrieve diagnostic events for a sandbox."""
content = obj.get_manager().get_diagnostic_events(sandbox_id, scope=scope)
render_diagnostic_content(obj, content, output_format, title="Diagnostic Events")