Skip to content

cli

cli

app module-attribute 

app = Typer(
    help="Run Python-defined sbx-agents runners.",
    no_args_is_help=True,
)

DockerSandbox

docker_args class-attribute instance-attribute 

docker_args: list[str] = Field(default_factory=list)

env class-attribute instance-attribute 

env: dict[str, str] = Field(default_factory=dict)

id class-attribute instance-attribute 

id: str = 'docker'

image class-attribute instance-attribute 

image: str = 'python:3.12-slim'

model_config class-attribute instance-attribute 

model_config = ConfigDict(arbitrary_types_allowed=True)

name class-attribute instance-attribute 

name: str | None = None

remove_on_exit class-attribute instance-attribute 

remove_on_exit: bool = True

workdir class-attribute instance-attribute 

workdir: str = '/workspace'

workspace instance-attribute 

workspace: Path

cleanup 

cleanup(session: SandboxSession) -> None

collect 

collect(session: SandboxSession) -> RunArtifacts

prepare 

prepare(
    agent: AgentLike, run_config: RunConfigLike | None
) -> SandboxSession

run 

run(
    session: SandboxSession, command: list[str]
) -> CommandResult

DockerSbxSandbox

branch class-attribute instance-attribute 

branch: str | None = None

codex_auth_from_host class-attribute instance-attribute 

codex_auth_from_host: bool = False

cpus class-attribute instance-attribute 

cpus: int | None = None

force_recreate class-attribute instance-attribute 

force_recreate: bool = False

id class-attribute instance-attribute 

id: str = 'docker_sbx'

memory class-attribute instance-attribute 

memory: str | None = None

model_config class-attribute instance-attribute 

model_config = ConfigDict(arbitrary_types_allowed=True)

name class-attribute instance-attribute 

name: str | None = None

network_allow class-attribute instance-attribute 

network_allow: list[str] = Field(default_factory=list)

remove_on_exit class-attribute instance-attribute 

remove_on_exit: bool = True

secret_env class-attribute instance-attribute 

secret_env: dict[str, str] = Field(default_factory=dict)

secret_oauth class-attribute instance-attribute 

secret_oauth: list[str] = Field(default_factory=list)

secret_oauth_refresh class-attribute instance-attribute 

secret_oauth_refresh: list[str] = Field(
    default_factory=list
)

workspace instance-attribute 

workspace: Path

check_agent_secrets classmethod 

check_agent_secrets(
    agent_id: str, *, timeout_seconds: int = 10
) -> None

check_available classmethod 

check_available() -> None

check_ready classmethod 

check_ready(*, timeout_seconds: int = 10) -> None

cleanup 

cleanup(session: SandboxSession) -> None

collect 

collect(session: SandboxSession) -> RunArtifacts

ensure_agent_auth 

ensure_agent_auth(
    agent: AgentLike,
    run_config: RunConfigLike | None = None,
    *,
    stream_output: bool = False,
) -> None

ensure_agent_secret 

ensure_agent_secret(
    agent_id: str,
    *,
    timeout_seconds: int = 10,
    stream_output: bool = False,
) -> None

has_global_secret classmethod 

has_global_secret(
    service: str, *, timeout_seconds: int = 10
) -> bool

is_available classmethod 

is_available() -> bool

is_ready classmethod 

is_ready(*, timeout_seconds: int = 10) -> bool

prepare 

prepare(
    agent: AgentLike, run_config: RunConfigLike | None
) -> SandboxSession

run 

run(
    session: SandboxSession, command: list[str]
) -> CommandResult

set_global_oauth_secret classmethod 

set_global_oauth_secret(
    service: str,
    *,
    timeout_seconds: int = 120,
    stream_output: bool = False,
) -> None

set_global_secret classmethod 

set_global_secret(
    service: str, value: str, *, timeout_seconds: int = 10
) -> None

PrettyStreamFilter 

PrettyStreamFilter(*, backend_id: str)

backend_id instance-attribute 

backend_id = backend_id

RunConfig

attachments class-attribute instance-attribute 

attachments: list[Path] = Field(default_factory=list)

continue_last class-attribute instance-attribute 

continue_last: bool = False

env class-attribute instance-attribute 

env: dict[str, str] = Field(default_factory=dict)

extra_args class-attribute instance-attribute 

extra_args: list[str] = Field(default_factory=list)

fork_session class-attribute instance-attribute 

fork_session: bool = False

forward_env class-attribute instance-attribute 

forward_env: list[str] = Field(default_factory=list)

json_events class-attribute instance-attribute 

json_events: bool = False

metadata class-attribute instance-attribute 

metadata: dict[str, Any] = Field(default_factory=dict)

network class-attribute instance-attribute 

network: str | None = None

output_schema class-attribute instance-attribute 

output_schema: Path | dict[str, Any] | None = None

permission class-attribute instance-attribute 

permission: PermissionPolicy | None = None

remove_on_exit class-attribute instance-attribute 

remove_on_exit: bool = True

resume_session_id class-attribute instance-attribute 

resume_session_id: str | None = None

secret_env class-attribute instance-attribute 

secret_env: list[str] = Field(default_factory=list)

secrets class-attribute instance-attribute 

secrets: list[str] = Field(default_factory=list)

stream_events class-attribute instance-attribute 

stream_events: bool = False

stream_output class-attribute instance-attribute 

stream_output: bool = False

timeout_seconds class-attribute instance-attribute 

timeout_seconds: int | None = None

RunResult

agent_backend instance-attribute 

agent_backend: str

agent_name instance-attribute 

agent_name: str

artifacts class-attribute instance-attribute 

artifacts: list[Artifact] = Field(default_factory=list)

command instance-attribute 

command: list[str]

diff class-attribute instance-attribute 

diff: str | None = None

duration_ms class-attribute instance-attribute 

duration_ms: int | None = None

events class-attribute instance-attribute 

events: list[dict[str, Any]] = Field(default_factory=list)

metadata class-attribute instance-attribute 

metadata: dict[str, Any] = Field(default_factory=dict)

output instance-attribute 

output: str

returncode instance-attribute 

returncode: int

sandbox_backend instance-attribute 

sandbox_backend: str

sandbox_name class-attribute instance-attribute 

sandbox_name: str | None = None

session_id class-attribute instance-attribute 

session_id: str | None = None

stderr instance-attribute 

stderr: str

stdout instance-attribute 

stdout: str

thread_id class-attribute instance-attribute 

thread_id: str | None = None

usage class-attribute instance-attribute 

usage: dict[str, Any] | None = None

from_parts classmethod 

from_parts(
    *,
    agent_name: str,
    agent_backend: str,
    sandbox_backend: str,
    sandbox_name: str | None,
    command_result: CommandResult,
    artifacts: RunArtifacts,
    events: list[dict[str, Any]] | None = None,
) -> RunResult

Runner 

Runner(
    agent: Agent,
    *,
    sandbox: SandboxBackend,
    run_config: RunConfig | None = None,
    default_prompt: str | None = None,
)

agent instance-attribute 

agent = agent

default_prompt instance-attribute 

default_prompt = default_prompt

run_config instance-attribute 

run_config = run_config

run_sync instance-attribute 

run_sync: Any

sandbox instance-attribute 

sandbox = sandbox

SandboxError

Raised when sandbox lifecycle or command execution fails.

_agent_secret_service_name 

_agent_secret_service_name(runner: Runner) -> str | None

_check_docker_sbx_local_provider 

_check_docker_sbx_local_provider(runner: Runner) -> None

_cli_run_config 

_cli_run_config(
    runner: Runner,
    *,
    stream_output: bool,
    raw: bool = False,
) -> RunConfig | None

_load_file_module 

_load_file_module(path: Path) -> ModuleType

_load_module 

_load_module(module_ref: str) -> ModuleType

_load_target 

_load_target(target: str) -> Any

_needs_sbx_secret 

_needs_sbx_secret(runner: Runner) -> bool

_preflight 

_preflight(runner: Runner, *, quiet: bool = False) -> None

_print_failure_hint 

_print_failure_hint(
    runner: Runner, result: RunResult
) -> None

_print_result 

_print_result(
    result: RunResult,
    *,
    json_output: bool,
    diff: bool,
    live_streamed: bool,
) -> None

doctor 

doctor(
    require: str | None = typer.Option(
        None,
        "--require",
        help="Require optional runtime: docker or docker-sbx",
    ),
) -> None

Check local runtime availability.

run 

run(
    target: str = typer.Argument(
        ...,
        help="Python target, e.g. main.py:runner or pkg.mod:runner",
    ),
    prompt: str | None = typer.Argument(
        None, help="Prompt override"
    ),
    json_output: bool = typer.Option(
        False, "--json", help="Print full RunResult as JSON"
    ),
    diff: bool = typer.Option(
        False,
        "--diff",
        help="Print collected diff after output",
    ),
    raw: bool = typer.Option(
        False, "--raw", help="Stream raw sandbox output"
    ),
    preflight: bool = typer.Option(
        True,
        "--preflight/--no-preflight",
        help="Check runtime readiness before run",
    ),
) -> None

Run a Python-defined Runner.