Sandbox interfaces reference

Python Sandbox computer-control, file, service, tunnel, and application interfaces in cua-sandbox 0.7.0.

These interfaces are exposed by Sandbox in the published cua-sandbox 0.7.0 package. A method's presence does not guarantee support by every transport. Fleet claims route computer-server operations through the selected named service; local and legacy transports have different capabilities.

Attribute	Class	Purpose
sb.shell	Shell	Run shell commands
sb.files	Files	Read, write, and transfer files
sb.mouse	Mouse	Mouse control
sb.keyboard	Keyboard	Keyboard control
sb.screen	Screen	Screenshots and screen info
sb.clipboard	Clipboard	Clipboard read/write
sb.tunnel	Tunnel	Port forwarding
sb.terminal	Terminal	PTY terminal sessions
sb.window	Window	Window management
sb.mobile	Mobile	Mobile (Android) touch and hardware-key control
sb.services	Services	Send requests to named services
sb.apps	Apps	Install and launch catalog applications

Shell#

async def run(command: str, timeout: int = 30, background: bool = False) -> CommandResult

CommandResult#

Field	Type	Description
stdout	str	Standard output
stderr	str	Standard error
returncode	int	Exit code
success	bool (property)	True if returncode == 0

Mouse#

async def click(x: int, y: int, button: str = 'left') -> None
async def right_click(x: int, y: int) -> None
async def double_click(x: int, y: int) -> None
async def move(x: int, y: int) -> None
async def scroll(x: int, y: int, scroll_x: int = 0, scroll_y: int = 3) -> None
async def mouse_down(x: int, y: int, button: str = 'left') -> None
async def mouse_up(x: int, y: int, button: str = 'left') -> None
async def drag(start_x: int, start_y: int, end_x: int, end_y: int, button: str = 'left') -> None

Keyboard#

async def type(text: str) -> None
# Type a string of text.
 
async def keypress(keys: Union[List[str], str]) -> None
# Press a key combination, e.g. ['ctrl', 'c'] or 'enter'.
 
async def key_down(key: str) -> None
async def key_up(key: str) -> None

Screen#

async def screenshot(format: str = 'png', quality: int = 95) -> bytes
# format: 'png' (lossless) or 'jpeg' (lossy). quality: 1-95, ignored for PNG.
 
async def screenshot_base64(format: str = 'png', quality: int = 95) -> str
# Screenshot as base64-encoded string.
 
async def size() -> Tuple[int, int]
# Returns (width, height) in pixels.

Clipboard#

async def get() -> str
# Returns current clipboard text.
 
async def set(text: str) -> None
# Sets clipboard text.

Tunnel#

def forward(*ports) -> _TunnelContext

Requests forwarding for one or more sandbox ports or Android abstract sockets from the connected transport. Supports await and async with; context exit closes the forwards.

In 0.7.0, the FleetTransport used by Pool.claim() does not implement tunnel.forward(). Use sb.services.request() for authenticated HTTP requests to a Fleet service. Local HTTP transports also do not implement this tunnel API; use sb.exposed_ports for ports forwarded at local startup.

ports may be int (TCP port) or str (Android abstract socket name, e.g. 'chrome_devtools_remote').

Returns:

single TunnelInfo when one target is given
dict[sandbox_port, TunnelInfo] when multiple targets are given

TunnelInfo#

Field	Type	Description
host	str	Host chosen by the transport
port	int	Port chosen by the transport
sandbox_port	int or str	Original port/socket inside the sandbox
url	str (property)	Explicit transport URL, or `http://{host}:{port}` when none is supplied

async def close() -> None
# Close this tunnel. No-op if already closed or inside a context manager.

Services#

Sends an authenticated request to a named service on the connected sandbox:

async def request(
    name: str, *, method: str, path: str, json: Any = None,
    headers: dict[str, str] | None = None,
) -> Any: ...

For Fleet claims, name must be in the bound sandbox's service list. The return value is an httpx.Response. method is the HTTP method, path is the service request path, json is an optional JSON body, and headers adds request headers. Transports without named service support raise NotImplementedError.

The released 0.7.0 Services interface also manages signed Fleet service URLs:

async def create_signed_url(
    name: str, *, expires_in_seconds: int, label: str | None = None
) -> SignedServiceURL: ...
async def list_signed_urls() -> list[SignedServiceURL]: ...
async def revoke_signed_url(signed_url: SignedServiceURL) -> None: ...

Transports without signed URL support raise NotImplementedError. A signed URL is a bearer credential; see Share a service with a signed URL for expiration and revocation guidance.

Files#

Paths refer to the sandbox unless a parameter explicitly names a local path. These async methods use the connected computer-server file operations:

Method	Return type	Purpose
`exists(path: str)`	`bool`	Tests whether a file exists
`is_dir(path: str)`	`bool`	Tests whether a directory exists
`size(path: str)`	`int`	Gets file size in bytes
`list(path: str)`	`list[FileEntry]`	Lists directory entries
`make_dir(path: str)`	`None`	Creates a directory
`remove_dir(path: str)`	`None`	Removes a directory through the server
`remove(path: str)`	`None`	Removes a file
`read_text(path: str)`	`str`	Reads text
`write_text(path: str, content: str)`	`None`	Writes text
`read_bytes(path: str, offset=0, length=None)`	`bytes`	Reads bytes, with an optional byte range
`write_bytes(path: str, content: bytes)`	`None`	Writes bytes
`upload(local_path, remote_path: str)`	`None`	Copies a host file into the sandbox
`download(remote_path: str, local_path)`	`None`	Copies a sandbox file to the host

Local paths accept str or pathlib.Path. FileEntry has name: str, path: str, is_dir: bool, and size: int or None.

Apps#

await sb.apps.install(app_id: str) and await sb.apps.launch(app_id: str) return CommandResult. They use the application catalog and guest installer; an application ID does not establish availability on every guest OS.

Terminal#

async def create(command: Optional[str] = None, cols: int = 80, rows: int = 24) -> dict
# Create a PTY session (default command is the login shell). Returns {'pid': int, 'cols': int, 'rows': int}.
 
async def send_input(pid: int, data: str) -> None
# Send input to a PTY session.
 
async def info(pid: int) -> Optional[dict]
# Return PTY session info, or None if the session is gone.
 
async def close(pid: int) -> bool
# Kill a PTY session. Returns True on success.

Window#

async def get_active_title() -> str
# Returns the title of the currently focused window.

Mobile#

Mobile (Android) touch and hardware-key control. Coordinates are in screen pixels. Single-touch methods use input tap/swipe via adb shell. Multi-touch gestures use adb root + MT Protocol B sendevent.

async def tap(x: int, y: int) -> None
async def long_press(x: int, y: int, duration_ms: int = 1000) -> None
async def double_tap(x: int, y: int, delay: float = 0.1) -> None
async def type_text(text: str) -> None
async def swipe(x1: int, y1: int, x2: int, y2: int, duration_ms: int = 300) -> None
async def scroll_up(x: int, y: int, distance: int = 600, duration_ms: int = 400) -> None
async def scroll_down(x: int, y: int, distance: int = 600, duration_ms: int = 400) -> None
async def scroll_left(x: int, y: int, distance: int = 400, duration_ms: int = 300) -> None
async def scroll_right(x: int, y: int, distance: int = 400, duration_ms: int = 300) -> None
async def fling(x1: int, y1: int, x2: int, y2: int) -> None
async def gesture(*finger_paths: tuple[int, int], duration_ms: int = 400, steps: int = 0) -> None
# N-finger gesture via MT Protocol B sendevent. Each positional arg is (x,y) waypoints for one finger.
# steps=0 = auto (duration_ms // 20, min 5).
async def pinch_in(cx: int, cy: int, spread: int = 300, duration_ms: int = 400) -> None
# Pinch-in (zoom out), two simultaneous fingers.
async def pinch_out(cx: int, cy: int, spread: int = 300, duration_ms: int = 400) -> None
# Pinch-out (zoom in), two simultaneous fingers.
async def key(keycode: int) -> None
async def home() -> None
async def back() -> None
async def recents() -> None
async def power() -> None
async def volume_up() -> None
async def volume_down() -> None
async def enter() -> None
async def backspace() -> None
async def wake() -> None
async def notifications() -> None
async def close_notifications() -> None