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.
"""Command execution commands: one interface, foreground stream or background tracking."""
from __future__ import annotations
import shlex
import sys
from collections.abc import Callable
from datetime import timedelta
import click
from opensandbox.models.execd import Execution, OutputMessage, RunCommandOpts
from opensandbox.models.execd_sync import ExecutionHandlersSync
from opensandbox_cli.client import ClientContext
from opensandbox_cli.utils import (
DURATION,
handle_errors,
output_option,
prepare_output,
)
@click.group("command", invoke_without_command=True)
@click.pass_context
def command_group(ctx: click.Context) -> None:
"""⚡ Execute commands in a sandbox."""
if ctx.invoked_subcommand is None:
click.echo(ctx.get_help())
def _stream_handlers() -> tuple[ExecutionHandlersSync, Callable[[], None]]:
"""Create stdout/stderr streaming handlers and a trailing-newline flusher."""
last_text = ""
def on_stdout(msg: OutputMessage) -> None:
nonlocal last_text
last_text = msg.text
sys.stdout.write(msg.text)
sys.stdout.flush()
def on_stderr(msg: OutputMessage) -> None:
nonlocal last_text
last_text = msg.text
sys.stderr.write(msg.text)
sys.stderr.flush()
def flush_newline() -> None:
if last_text and not last_text.endswith("\n"):
sys.stdout.write("\n")
sys.stdout.flush()
return ExecutionHandlersSync(on_stdout=on_stdout, on_stderr=on_stderr), flush_newline
def _run_command(
obj: ClientContext,
sandbox_id: str,
command: tuple[str, ...],
background: bool,
workdir: str | None,
timeout: timedelta | None,
output_format: str | None,
argv: bool = False,
) -> None:
"""Shared implementation for ``command run``.
Foreground mode streams output and allows only ``-o raw``; background mode
returns a tracked execution object and allows structured output. The payload
is joined into one shell command string unless ``argv`` sends it as a
literal argv list (needs an argv-capable execd).
"""
allowed = ("table", "json", "yaml") if background else ("raw",)
fallback = "table" if background else "raw"
prepare_output(obj, output_format, allowed=allowed, fallback=fallback)
payload: str | list[str]
if argv:
payload = list(command)
else:
payload = " ".join(shlex.quote(arg) for arg in command)
sandbox = obj.connect_sandbox(sandbox_id)
try:
opts = RunCommandOpts(
background=background,
working_directory=workdir,
timeout=timeout,
)
if background:
execution = sandbox.commands.run(payload, opts=opts)
_handle_execution_error(obj, execution, background=True)
obj.output.success_panel(
{
"execution_id": execution.id,
"sandbox_id": sandbox_id,
"mode": "background",
},
title="Background Command Started",
)
return
handlers, flush_newline = _stream_handlers()
execution = sandbox.commands.run(payload, opts=opts, handlers=handlers)
flush_newline()
_handle_execution_error(obj, execution)
finally:
sandbox.close()
def _handle_execution_error(
obj: ClientContext, execution: Execution, *, background: bool = False
) -> None:
"""Exit non-zero on execution errors or missing completion/startup confirmation."""
if execution.error:
obj.output.error_panel(
f"{execution.error.name}: {execution.error.value}",
title="Execution Error",
)
sys.exit(1)
if execution.complete is None:
confirmation = (
"background command startup was confirmed" if background else "the command finished"
)
obj.output.error_panel(
f"The output stream ended before {confirmation}, so its result is unknown.",
title="Execution Incomplete",
)
sys.exit(1)
@command_group.command(
"run",
help="Run a command in a sandbox. Use `--` before the sandbox command payload.",
epilog=(
"Separator rule: use `--` before the sandbox command payload.\n\n"
"By default the payload is joined into one shell command string. Add "
"`--argv` to pass the arguments to the executable as-is (no shell), so "
"literal `$HOME`, quotes, and empty strings are preserved; this needs a "
"sandbox image whose execd accepts argv requests."
),
)
@click.argument("sandbox_id")
@click.argument("command", nargs=-1, required=True)
@click.option("-d", "--background", is_flag=True, default=False, help="Run in background.")
@click.option("-w", "--workdir", default=None, help="Working directory.")
@click.option("-t", "--timeout", type=DURATION, default=None, help="Command timeout (e.g. 30s, 5m).")
@click.option(
"--argv",
is_flag=True,
default=False,
help="Pass the payload as a literal argv list (no shell). Requires an argv-capable execd.",
)
@output_option("table", "json", "yaml", "raw")
@click.pass_obj
@handle_errors
def command_run(
obj: ClientContext,
sandbox_id: str,
command: tuple[str, ...],
background: bool,
workdir: str | None,
timeout: timedelta | None,
argv: bool,
output_format: str | None,
) -> None:
"""Run a command in a sandbox.
Default mode streams output directly. Add ``--background`` to return a
tracked execution object instead. Use ``--`` before the sandbox command payload.
The payload is sent as a shell command string unless ``--argv`` is given.
"""
_run_command(
obj,
sandbox_id,
command,
background,
workdir,
timeout,
output_format,
argv=argv,
)
@command_group.command("status")
@click.argument("sandbox_id")
@click.argument("execution_id")
@output_option("table", "json", "yaml")
@click.pass_obj
@handle_errors
def command_status(
obj: ClientContext,
sandbox_id: str,
execution_id: str,
output_format: str | None,
) -> None:
"""Get command execution status."""
prepare_output(obj, output_format, allowed=("table", "json", "yaml"), fallback="table")
sandbox = obj.connect_sandbox(sandbox_id)
try:
status = sandbox.commands.get_command_status(execution_id)
obj.output.print_model(status, title="Command Status")
finally:
sandbox.close()
@command_group.command("logs")
@click.argument("sandbox_id")
@click.argument("execution_id")
@click.option("--cursor", type=int, default=None, help="Cursor for incremental reads.")
@output_option("table", "json", "yaml", "raw")
@click.pass_obj
@handle_errors
def command_logs(
obj: ClientContext,
sandbox_id: str,
execution_id: str,
cursor: int | None,
output_format: str | None,
) -> None:
"""Get background command logs."""
prepare_output(
obj, output_format, allowed=("table", "json", "yaml", "raw"), fallback="table"
)
sandbox = obj.connect_sandbox(sandbox_id)
try:
logs = sandbox.commands.get_background_command_logs(execution_id, cursor=cursor)
if obj.output.fmt in ("json", "yaml"):
obj.output.print_model(logs, title="Command Logs")
elif obj.output.fmt == "raw":
click.echo(logs.content)
else:
obj.output.panel(logs.content, title="Command Logs")
finally:
sandbox.close()
@command_group.command("interrupt")
@click.argument("sandbox_id")
@click.argument("execution_id")
@output_option("table", "json", "yaml")
@click.pass_obj
@handle_errors
def command_interrupt(
obj: ClientContext,
sandbox_id: str,
execution_id: str,
output_format: str | None,
) -> None:
"""Interrupt a running command."""
prepare_output(obj, output_format, allowed=("table", "json", "yaml"), fallback="table")
sandbox = obj.connect_sandbox(sandbox_id)
try:
sandbox.commands.interrupt(execution_id)
obj.output.success(f"Interrupted: {execution_id}")
finally:
sandbox.close()
@command_group.group("session", invoke_without_command=True)
@click.pass_context
def session_group(ctx: click.Context) -> None:
"""Manage persistent bash sessions."""
if ctx.invoked_subcommand is None:
click.echo(ctx.get_help())
@session_group.command("create")
@click.argument("sandbox_id")
@click.option("-w", "--workdir", default=None, help="Initial working directory.")
@output_option("table", "json", "yaml")
@click.pass_obj
@handle_errors
def session_create(
obj: ClientContext,
sandbox_id: str,
workdir: str | None,
output_format: str | None,
) -> None:
"""Create a persistent bash session."""
prepare_output(obj, output_format, allowed=("table", "json", "yaml"), fallback="table")
sandbox = obj.connect_sandbox(sandbox_id)
try:
session_id = sandbox.commands.create_session(working_directory=workdir)
obj.output.success_panel(
{
"sandbox_id": sandbox.id,
"session_id": session_id,
"working_directory": workdir,
},
title="Session Created",
)
finally:
sandbox.close()
@session_group.command(
"run",
help="Run a command in an existing bash session. Use `--` before the sandbox command payload.",
epilog="Separator rule: use `--` before the sandbox command payload.",
)
@click.argument("sandbox_id")
@click.argument("session_id")
@click.argument("command", nargs=-1, required=True)
@click.option("-w", "--workdir", default=None, help="Working directory override for this run.")
@click.option("-t", "--timeout", type=DURATION, default=None, help="Command timeout (e.g. 30s, 5m).")
@output_option("raw", help_text="Output format: raw.")
@click.pass_obj
@handle_errors
def session_run(
obj: ClientContext,
sandbox_id: str,
session_id: str,
command: tuple[str, ...],
workdir: str | None,
timeout: timedelta | None,
output_format: str | None,
) -> None:
"""Run a command in an existing bash session. Use `--` before the sandbox command payload."""
prepare_output(obj, output_format, allowed=("raw",), fallback="raw")
cmd_str = " ".join(shlex.quote(arg) for arg in command)
sandbox = obj.connect_sandbox(sandbox_id)
try:
handlers, flush_newline = _stream_handlers()
execution = sandbox.commands.run_in_session(
session_id,
cmd_str,
working_directory=workdir,
timeout=timeout,
handlers=handlers,
)
flush_newline()
_handle_execution_error(obj, execution)
finally:
sandbox.close()
@session_group.command("delete")
@click.argument("sandbox_id")
@click.argument("session_id")
@output_option("table", "json", "yaml")
@click.pass_obj
@handle_errors
def session_delete(
obj: ClientContext,
sandbox_id: str,
session_id: str,
output_format: str | None,
) -> None:
"""Delete a persistent bash session."""
prepare_output(obj, output_format, allowed=("table", "json", "yaml"), fallback="table")
sandbox = obj.connect_sandbox(sandbox_id)
try:
sandbox.commands.delete_session(session_id)
obj.output.success(f"Deleted session: {session_id}")
finally:
sandbox.close()