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.
"""File operation commands: cat, write, upload, download, rm, mv, mkdir, rmdir, search, info, chmod, replace."""
from __future__ import annotations
import os
import stat
import sys
from pathlib import Path
from tempfile import TemporaryDirectory
import click
from opensandbox_cli.client import ClientContext
from opensandbox_cli.utils import handle_errors, output_option, prepare_output
def _parse_permission_mode(mode: str) -> int:
"""Parse a permission mode string like 644 or 755."""
try:
return int(mode)
except ValueError as exc:
raise click.BadParameter(
f"Invalid permission mode '{mode}'. Use a permission value like 644 or 755."
) from exc
@click.group("file", invoke_without_command=True)
@click.pass_context
def file_group(ctx: click.Context) -> None:
"""📁 File operations on a sandbox."""
if ctx.invoked_subcommand is None:
click.echo(ctx.get_help())
@file_group.command("cat")
@click.argument("sandbox_id")
@click.argument("path")
@click.option("--encoding", default="utf-8", help="File encoding.")
@output_option("raw", help_text="Output format: raw.")
@click.pass_obj
@handle_errors
def file_cat(
obj: ClientContext,
sandbox_id: str,
path: str,
encoding: str,
output_format: str | None,
) -> None:
"""Read a file from the sandbox."""
prepare_output(obj, output_format, allowed=("raw",), fallback="raw")
sandbox = obj.connect_sandbox(sandbox_id)
try:
content = sandbox.files.read_file(path, encoding=encoding)
click.echo(content, nl=False)
finally:
sandbox.close()
@file_group.command("write")
@click.argument("sandbox_id")
@click.argument("path")
@click.option("--content", "-c", default=None, help="Content to write. Reads from stdin if not provided.")
@click.option("--encoding", default="utf-8", help="File encoding.")
@click.option("--mode", default=None, help="File permission mode (e.g. 0644).")
@click.option("--owner", default=None, help="File owner.")
@click.option("--group", default=None, help="File group.")
@output_option("table", "json", "yaml")
@click.pass_obj
@handle_errors
def file_write(
obj: ClientContext,
sandbox_id: str,
path: str,
content: str | None,
encoding: str,
mode: str | None,
owner: str | None,
group: str | None,
output_format: str | None,
) -> None:
"""Write content to a file in the sandbox."""
prepare_output(obj, output_format, allowed=("table", "json", "yaml"), fallback="table")
file_content = content
if file_content is None:
if sys.stdin.isatty():
click.echo("Reading from stdin (Ctrl+D to finish):", err=True)
file_content = sys.stdin.read()
sandbox = obj.connect_sandbox(sandbox_id)
try:
kwargs: dict = {"encoding": encoding}
if mode is not None:
kwargs["mode"] = _parse_permission_mode(mode)
if owner is not None:
kwargs["owner"] = owner
if group is not None:
kwargs["group"] = group
sandbox.files.write_file(path, file_content, **kwargs)
obj.output.success(f"Written: {path}")
finally:
sandbox.close()
@file_group.command("upload")
@click.argument("sandbox_id")
@click.argument("local_path", type=click.Path(exists=True))
@click.argument("remote_path")
@output_option("table", "json", "yaml")
@click.pass_obj
@handle_errors
def file_upload(
obj: ClientContext,
sandbox_id: str,
local_path: str,
remote_path: str,
output_format: str | None,
) -> None:
"""Upload a local file to the sandbox."""
prepare_output(obj, output_format, allowed=("table", "json", "yaml"), fallback="table")
sandbox = obj.connect_sandbox(sandbox_id)
try:
with Path(local_path).open("rb") as data:
sandbox.files.write_file(remote_path, data)
obj.output.success(f"Uploaded: {local_path} → {remote_path}")
finally:
sandbox.close()
@file_group.command("download")
@click.argument("sandbox_id")
@click.argument("remote_path")
@click.argument("local_path", type=click.Path(readable=False))
@output_option("table", "json", "yaml")
@click.pass_obj
@handle_errors
def file_download(
obj: ClientContext,
sandbox_id: str,
remote_path: str,
local_path: str,
output_format: str | None,
) -> None:
"""Download a file to the host.
Regular files are replaced only on success. Devices and named pipes receive
data directly, including partial data if the download fails.
Destinations referring to stdout stream directly and omit the success message.
"""
prepare_output(obj, output_format, allowed=("table", "json", "yaml"), fallback="table")
sandbox = obj.connect_sandbox(sandbox_id)
try:
destination = Path(local_path)
destination.parent.mkdir(parents=True, exist_ok=True)
try:
destination_stat = destination.stat()
except FileNotFoundError:
destination_stat = None
destination_mode = destination_stat.st_mode if destination_stat is not None else None
try:
destination_is_stdout = destination_stat is not None and os.path.samestat(
destination_stat, os.fstat(sys.stdout.fileno())
)
if not destination_is_stdout and destination_stat is not None:
# macOS reports different stat/fstat identities for /dev/fd entries.
destination_is_stdout = destination.samefile(f"/dev/fd/{sys.stdout.fileno()}")
except (OSError, ValueError):
# Embedded callers may capture stdout in a stream without a descriptor.
destination_is_stdout = False
if destination_is_stdout or (
destination_mode is not None and not stat.S_ISREG(destination_mode)
):
# Special files are stream targets and must never be replaced.
# Duplicate stdout to preserve its offset/append mode and keep it open.
stream = (
os.fdopen(os.dup(sys.stdout.fileno()), "wb")
if destination_is_stdout
else destination.open("wb")
)
with stream as out:
for chunk in sandbox.files.read_bytes_stream(remote_path):
out.write(chunk)
else:
destination = destination.resolve()
if destination_mode is not None:
# Check write permission without truncating the existing file.
os.close(os.open(destination, os.O_WRONLY))
with TemporaryDirectory(prefix=".osb-download-", dir=destination.parent) as temp_dir:
staged = Path(temp_dir) / "download"
with staged.open("wb") as out:
for chunk in sandbox.files.read_bytes_stream(remote_path):
out.write(chunk)
if destination_mode is not None:
staged.chmod(destination_mode & 0o777)
staged.replace(destination)
if not destination_is_stdout:
obj.output.success(f"Downloaded: {remote_path} → {local_path}")
finally:
sandbox.close()
@file_group.command("rm")
@click.argument("sandbox_id")
@click.argument("paths", nargs=-1, required=True)
@output_option("table", "json", "yaml")
@click.pass_obj
@handle_errors
def file_rm(
obj: ClientContext,
sandbox_id: str,
paths: tuple[str, ...],
output_format: str | None,
) -> None:
"""Delete files from the sandbox."""
prepare_output(obj, output_format, allowed=("table", "json", "yaml"), fallback="table")
sandbox = obj.connect_sandbox(sandbox_id)
try:
sandbox.files.delete_files(list(paths))
obj.output.print_rows(
[{"path": p, "status": "deleted"} for p in paths],
columns=["path", "status"],
title="Deleted Files",
)
finally:
sandbox.close()
@file_group.command("mv")
@click.argument("sandbox_id")
@click.argument("source")
@click.argument("destination")
@output_option("table", "json", "yaml")
@click.pass_obj
@handle_errors
def file_mv(
obj: ClientContext,
sandbox_id: str,
source: str,
destination: str,
output_format: str | None,
) -> None:
"""Move/rename a file in the sandbox."""
prepare_output(obj, output_format, allowed=("table", "json", "yaml"), fallback="table")
from opensandbox.models.filesystem import MoveEntry
sandbox = obj.connect_sandbox(sandbox_id)
try:
sandbox.files.move_files([MoveEntry(source=source, destination=destination)])
obj.output.success(f"Moved: {source} → {destination}")
finally:
sandbox.close()
@file_group.command("mkdir")
@click.argument("sandbox_id")
@click.argument("paths", nargs=-1, required=True)
@click.option("--mode", default=None, help="Directory permission mode.")
@click.option("--owner", default=None, help="Directory owner.")
@click.option("--group", default=None, help="Directory group.")
@output_option("table", "json", "yaml")
@click.pass_obj
@handle_errors
def file_mkdir(
obj: ClientContext,
sandbox_id: str,
paths: tuple[str, ...],
mode: str | None,
owner: str | None,
group: str | None,
output_format: str | None,
) -> None:
"""Create directories in the sandbox."""
prepare_output(obj, output_format, allowed=("table", "json", "yaml"), fallback="table")
from opensandbox.models.filesystem import WriteEntry
sandbox = obj.connect_sandbox(sandbox_id)
try:
entries = []
for p in paths:
kwargs: dict = {"path": p}
if mode is not None:
kwargs["mode"] = _parse_permission_mode(mode)
if owner is not None:
kwargs["owner"] = owner
if group is not None:
kwargs["group"] = group
entries.append(WriteEntry(**kwargs))
sandbox.files.create_directories(entries)
obj.output.print_rows(
[{"path": p, "status": "created"} for p in paths],
columns=["path", "status"],
title="Created Directories",
)
finally:
sandbox.close()
@file_group.command("rmdir")
@click.argument("sandbox_id")
@click.argument("paths", nargs=-1, required=True)
@output_option("table", "json", "yaml")
@click.pass_obj
@handle_errors
def file_rmdir(
obj: ClientContext,
sandbox_id: str,
paths: tuple[str, ...],
output_format: str | None,
) -> None:
"""Delete directories from the sandbox."""
prepare_output(obj, output_format, allowed=("table", "json", "yaml"), fallback="table")
sandbox = obj.connect_sandbox(sandbox_id)
try:
sandbox.files.delete_directories(list(paths))
obj.output.print_rows(
[{"path": p, "status": "removed"} for p in paths],
columns=["path", "status"],
title="Removed Directories",
)
finally:
sandbox.close()
@file_group.command("search")
@click.argument("sandbox_id")
@click.argument("path")
@click.option("--pattern", "-p", required=True, help="Glob pattern to search for.")
@output_option("table", "json", "yaml")
@click.pass_obj
@handle_errors
def file_search(
obj: ClientContext,
sandbox_id: str,
path: str,
pattern: str,
output_format: str | None,
) -> None:
"""Search for files in the sandbox."""
prepare_output(obj, output_format, allowed=("table", "json", "yaml"), fallback="table")
from opensandbox.models.filesystem import SearchEntry
sandbox = obj.connect_sandbox(sandbox_id)
try:
results = sandbox.files.search(SearchEntry(path=path, pattern=pattern))
if not results:
if obj.output.fmt in ("json", "yaml"):
obj.output.print_models([], columns=[])
else:
obj.output.info("No files found.")
return
if obj.output.fmt in ("json", "yaml"):
obj.output.print_models(results, columns=["path", "size", "mode", "owner", "modified_at"])
else:
obj.output.print_models(results, columns=["path", "size", "owner"], title="Search Results")
finally:
sandbox.close()
@file_group.command("info")
@click.argument("sandbox_id")
@click.argument("paths", nargs=-1, required=True)
@output_option("table", "json", "yaml")
@click.pass_obj
@handle_errors
def file_info(
obj: ClientContext,
sandbox_id: str,
paths: tuple[str, ...],
output_format: str | None,
) -> None:
"""Get file/directory info."""
prepare_output(obj, output_format, allowed=("table", "json", "yaml"), fallback="table")
sandbox = obj.connect_sandbox(sandbox_id)
try:
info_map = sandbox.files.get_file_info(list(paths))
rows = [{"path": path, **entry.model_dump(mode="json")} for path, entry in info_map.items()]
obj.output.print_rows(
rows,
columns=["path", "size", "mode", "owner", "group", "created_at", "modified_at"],
title="Path Info",
)
finally:
sandbox.close()
@file_group.command("chmod")
@click.argument("sandbox_id")
@click.argument("path")
@click.option("--mode", required=True, help="Permission mode (e.g. 0755).")
@click.option("--owner", default=None, help="File owner.")
@click.option("--group", default=None, help="File group.")
@output_option("table", "json", "yaml")
@click.pass_obj
@handle_errors
def file_chmod(
obj: ClientContext,
sandbox_id: str,
path: str,
mode: str,
owner: str | None,
group: str | None,
output_format: str | None,
) -> None:
"""Set file permissions."""
prepare_output(obj, output_format, allowed=("table", "json", "yaml"), fallback="table")
from opensandbox.models.filesystem import SetPermissionEntry
sandbox = obj.connect_sandbox(sandbox_id)
try:
sandbox.files.set_permissions(
[
SetPermissionEntry(
path=path,
mode=_parse_permission_mode(mode),
owner=owner,
group=group,
)
]
)
obj.output.success(f"Permissions set: {path}")
finally:
sandbox.close()
@file_group.command("replace")
@click.argument("sandbox_id")
@click.argument("path")
@click.option("--old", required=True, help="Text to search for.")
@click.option("--new", required=True, help="Replacement text.")
@output_option("table", "json", "yaml")
@click.pass_obj
@handle_errors
def file_replace(
obj: ClientContext,
sandbox_id: str,
path: str,
old: str,
new: str,
output_format: str | None,
) -> None:
"""Replace content in a file."""
prepare_output(obj, output_format, allowed=("table", "json", "yaml"), fallback="table")
from opensandbox.models.filesystem import ContentReplaceEntry
sandbox = obj.connect_sandbox(sandbox_id)
try:
sandbox.files.replace_contents(
[ContentReplaceEntry(path=path, old_content=old, new_content=new)]
)
obj.output.success(f"Replaced in: {path}")
finally:
sandbox.close()