gbox_sdk.wrapper.box package

Subpackages

Submodules

gbox_sdk.wrapper.box.action module

class gbox_sdk.wrapper.box.action.ClipboardOperator(client, box_id)

Bases: object

get()

Get the clipboard content.

Return type:

str

Example:
>>> response = myBox.action.clipboard.get()
set(content)

Set the clipboard content

Return type:

None

Args:

content: The content to set the clipboard content

Example:
>>> response = myBox.action.clipboard.set("Hello, world!")
class gbox_sdk.wrapper.box.action.ElementManager(client, box_id, elements)

Bases: object

The elements manager contains a list of detected elements.

get(id)

Get an element by its id.

Return type:

DetectedElement

list()

List all elements.

Return type:

List[DetectedElement]

class gbox_sdk.wrapper.box.action.ElementsOperator(client, box_id)

Bases: object

class DetectResult(elements, screenshot)

Bases: object

Result of element detection operation.

detect(screenshot=<gbox_sdk.Omit object>)

Detect and identify interactive UI elements in the current screen.

Return type:

DetectResult

Args:
screenshot: Detect elements screenshot options. See

gbox_sdk.types.v1.boxes.action_elements_detect_params.Screenshot.

Returns:

A DetectResult object with: - elements: an ElementManager for convenient access to detected elements - screenshot: the screenshot metadata from detection

Example:
>>> response = myBox.action.elements.detect()
>>> first = response.elements.list()[0]
class gbox_sdk.wrapper.box.action.RecordingOperator(client, box_id)

Bases: object

start()

Start recording the box screen.

Only one recording can be active at a time. If a recording is already in progress, starting a new recording will stop the previous one and keep only the latest recording.

Return type:

None

Args:
duration: Duration of the recording. Default is 30m, max is 30m. The recording will

automatically stop when the duration time is reached.

Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Maximum allowed: 30m

Example:
>>> response = myBox.action.recording.start(duration="30m")
stop()

Stop recording the box screen.

Return type:

ActionRecordingStopResponse

Returns:

ActionRecordingStopResponse: The response from the box screen recording stop.

Example:
>>> response = myBox.action.recording.stop()
class gbox_sdk.wrapper.box.action.RecordingRewindOperator(client, box_id)

Bases: object

disable()

Disable the box screen recording rewind.

Return type:

None

Example:
>>> response = myBox.action.recording.rewind.disable()
enable()

Enable the box screen recording rewind.

Return type:

None

Example:
>>> response = myBox.action.recording.rewind.enable()
extract(duration)

Rewind and capture the device’s background screen recording from a specified time period.

Return type:

ActionRewindExtractResponse

Args:
duration: How far back in time to rewind for extracting recorded video. This specifies the

duration to go back from the current moment (e.g., ’30s’ rewinds 30 seconds to get recent recorded activity). Default is 30s, max is 5m.

Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Maximum allowed: 5m

Returns:

ActionRewindExtractResponse: The response from the box screen recording rewind extract.

Example:
>>> response = myBox.action.recording.rewind.extract(duration="30s")

gbox_sdk.wrapper.box.base module

gbox_sdk.wrapper.box.browser module

class gbox_sdk.wrapper.box.browser.BrowserTabOperator(*, client, box_id, data)

Bases: object

Provides operations related to browser tabs for a specific box.

Args:

client (GboxClient): The GboxClient instance used to interact with the API. box_id (str): The unique identifier of the box.

update(url)

Navigate an existing browser tab to a new URL.

This endpoint updates the specified tab by navigating it to the provided URL and returns the updated tab information. The browser will wait for the DOM content to be loaded before returning the response. If the navigation fails due to an invalid URL or network issues, an error will be returned. The updated tab information will include the new title, final URL (after any redirects), and favicon from the new page.

Return type:

BrowserUpdateTabResponse

Args:

url: The tab new url

Returns:

BrowserUpdateTabResponse: The updated tab information.

Example:
>>> box.browser.tab.update("https://www.google.com")

gbox_sdk.wrapper.box.file_system module

gbox_sdk.wrapper.box.linux module

Module contents

class gbox_sdk.wrapper.box.ActionOperator(client, box_id)

Bases: object

Provides high-level action operations for a specific box using the GboxClient.

Methods correspond to various box actions such as click, drag, swipe, type, screenshot, etc.

click(*, x=<gbox_sdk.Omit object>, y=<gbox_sdk.Omit object>, button=<gbox_sdk.Omit object>, double=<gbox_sdk.Omit object>, include_screenshot=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, target=<gbox_sdk.Omit object>)
Return type:

ActionResult

drag(*, end=<gbox_sdk.Omit object>, start=<gbox_sdk.Omit object>, duration=<gbox_sdk.Omit object>, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, path=<gbox_sdk.Omit object>)
Return type:

ActionResult

extract(*, instruction, schema=<gbox_sdk.Omit object>)

Extract data from the UI interface using a JSON schema.

Return type:

ActionExtractResponse

Args:

instruction: The instruction of the action to extract data from the UI interface

schema: JSON Schema defining the structure of data to extract. Supports object, array,

string, number, boolean types with validation rules.

Common use cases:

  • Extract text content: { “type”: “string” }

  • Extract structured data: { “type”: “object”, “properties”: {…} }

  • Extract lists: { “type”: “array”, “items”: {…} }

  • Extract with validation: Add constraints like “required”, “enum”, “pattern”, etc.

Returns:

ActionExtractResponse: The response containing the extracted data.

Example:
>>> response = myBox.action.extract(
...     instruction="Extract the user name from the profile",
...     schema={"type": "string"},
... )
get_settings()

Get the box action settings

Return type:

ActionSettingsResponse

Returns:

ActionSettingsResponse: The response from the box action settings.

Example:
>>> response = myBox.action.get_setting()
long_press(*, x=<gbox_sdk.Omit object>, y=<gbox_sdk.Omit object>, duration=<gbox_sdk.Omit object>, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, target=<gbox_sdk.Omit object>)
Return type:

ActionResult

move(*, x, y, include_screenshot=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>)

Move an element or pointer on the box.

Return type:

ActionResult

Args:

x: X coordinate to move to

y: Y coordinate to move to

include_screenshot: ⚠️ DEPRECATED: Use options.screenshot.phases instead. This field will be

ignored when options.screenshot is provided. Whether to include screenshots in the action response. If false, the screenshot object will still be returned but with empty URIs. Default is false.

options: Action common options

output_format: ⚠️ DEPRECATED: Use options.screenshot.outputFormat instead. Type of the URI.

default is base64. This field will be ignored when options.screenshot is provided.

presigned_expires_in: ⚠️ DEPRECATED: Use options.screenshot.presignedExpiresIn instead. Presigned

url expires in. Only takes effect when outputFormat is storageKey. This field will be ignored when options.screenshot is provided.

Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 30m

screenshot_delay: ⚠️ DEPRECATED: Use options.screenshot.delay instead. This field will be

ignored when options.screenshot is provided.

Delay after performing the action, before taking the final screenshot.

Execution flow:

  1. Take screenshot before action

  2. Perform the action

  3. Wait for screenshotDelay (this parameter)

  4. Take screenshot after action

Example: ‘500ms’ means wait 500ms after the action before capturing the final screenshot.

Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 500ms Maximum allowed: 30s

Returns:

ActionMoveResponse: The response from the move action.

Example:
>>> response = myBox.action.move(x=200, y=300)
press_button(buttons, *, include_screenshot=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>)

Press device buttons like power, volume, home, back, etc.

Return type:

ActionResult

Args:

buttons: Button to press

include_screenshot: ⚠️ DEPRECATED: Use options.screenshot.phases instead. This field will be

ignored when options.screenshot is provided. Whether to include screenshots in the action response. If false, the screenshot object will still be returned but with empty URIs. Default is false.

options: Action common options

output_format: ⚠️ DEPRECATED: Use options.screenshot.outputFormat instead. Type of the URI.

default is base64. This field will be ignored when options.screenshot is provided.

presigned_expires_in: ⚠️ DEPRECATED: Use options.screenshot.presignedExpiresIn instead. Presigned

url expires in. Only takes effect when outputFormat is storageKey. This field will be ignored when options.screenshot is provided.

Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 30m

screenshot_delay: ⚠️ DEPRECATED: Use options.screenshot.delay instead. This field will be

ignored when options.screenshot is provided.

Delay after performing the action, before taking the final screenshot.

Execution flow:

  1. Take screenshot before action

  2. Perform the action

  3. Wait for screenshotDelay (this parameter)

  4. Take screenshot after action

Example: ‘500ms’ means wait 500ms after the action before capturing the final screenshot.

Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 500ms Maximum allowed: 30s

Returns:

ActionPressButtonResponse: The response from the button press action.

Example:
>>> response = myBox.action.press_button(buttons=["power"])
press_key(*, keys, combination=<gbox_sdk.Omit object>, include_screenshot=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>)

Simulates pressing a specific key by triggering the complete keyboard key event chain (keydown, keypress, keyup). Use this to activate keyboard key event listeners such as shortcuts or form submissions.

Return type:

ActionResult

Args:
keys: This is an array of keyboard keys to press. Supports cross-platform

compatibility.

combination: Whether to press keys as combination (simultaneously) or sequentially. When

true, all keys are pressed together as a shortcut (e.g., Ctrl+C). When false, keys are pressed one by one in sequence.

include_screenshot: ⚠️ DEPRECATED: Use options.screenshot.phases instead. This field will be

ignored when options.screenshot is provided. Whether to include screenshots in the action response. If false, the screenshot object will still be returned but with empty URIs. Default is false.

options: Action common options

output_format: ⚠️ DEPRECATED: Use options.screenshot.outputFormat instead. Type of the URI.

default is base64. This field will be ignored when options.screenshot is provided.

presigned_expires_in: ⚠️ DEPRECATED: Use options.screenshot.presignedExpiresIn instead. Presigned

url expires in. Only takes effect when outputFormat is storageKey. This field will be ignored when options.screenshot is provided.

Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 30m

screenshot_delay: ⚠️ DEPRECATED: Use options.screenshot.delay instead. This field will be

ignored when options.screenshot is provided.

Delay after performing the action, before taking the final screenshot.

Execution flow:

  1. Take screenshot before action

  2. Perform the action

  3. Wait for screenshotDelay (this parameter)

  4. Take screenshot after action

Example: ‘500ms’ means wait 500ms after the action before capturing the final screenshot.

Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 500ms Maximum allowed: 30s

Returns:

ActionPressKeyResponse: The response from the key press action.

Example:
>>> response = myBox.action.press_key(keys=["enter"])
>>> response = myBox.action.press_key(keys=["control", "c"], combination=True)
reset_settings()

Reset the box action settings

Return type:

ActionSettingsResetResponse

Returns:

ActionSettingsResetResponse: The response from the box action settings reset.

Example:
>>> response = myBox.action.reset_settings()
screen_layout()

Get the current structured screen layout information.

Return type:

ActionScreenLayoutResponse

Returns:

ActionScreenLayoutResponse: The response containing the screen layout data.

Example:
>>> response = myBox.action.screen_layout()
screen_recording_start()

Start recording the box screen.

Only one recording can be active at a time. If a recording is already in progress, starting a new recording will stop the previous one and keep only the latest recording.

Return type:

None

Args:
duration: Duration of the recording. Default is 30m, max is 30m. The recording will

automatically stop when the duration time is reached.

Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Maximum allowed: 30m

Example:
>>> response = myBox.action.screen_recording_start(duration="30m")
screen_recording_stop()

Stop recording the screen.

Return type:

ActionRecordingStopResponse

Returns:

ActionRecordingStopResponse: The response from the screen recording stop action.

Example:
>>> response = myBox.action.screen_recording_stop()
screen_rotation(orientation, *, include_screenshot=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>)

Rotate the screen orientation.

Note that even after rotating the screen, applications or system layouts may not automatically adapt to the gravity sensor changes, so visual changes may not always occur.

Return type:

ActionResult

Args:

orientation: Target screen orientation

include_screenshot: Whether to include screenshots in the action response. If false, the screenshot

object will still be returned but with empty URIs. Default is false.

output_format: Type of the URI. default is base64.

presigned_expires_in: Presigned url expires in. Only takes effect when outputFormat is storageKey.

Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 30m

screenshot_delay: Delay after performing the action, before taking the final screenshot.

Execution flow:

  1. Take screenshot before action

  2. Perform the action

  3. Wait for screenshotDelay (this parameter)

  4. Take screenshot after action

Example: ‘500ms’ means wait 500ms after the action before capturing the final screenshot.

Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 500ms Maximum allowed: 30s

Returns:

ActionScreenRotationResponse: The response from the screen rotation action.

Example:
>>> response = myBox.action.screen_rotation("landscapeLeft")
>>> response = myBox.action.screen_rotation(
...     orientation="landscapeLeft",
...     include_screenshot=True,
...     output_format="storageKey",
...     presigned_expires_in="30m",
...     screenshot_delay="500ms",
... )
screenshot(*, path=<gbox_sdk.Omit object>, clip=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, save_to_album=<gbox_sdk.Omit object>)

Take a screenshot of the box.

Return type:

ActionScreenshotResponse

Args:

clip: Clipping region for screenshot capture

output_format: Type of the URI. default is base64.

presigned_expires_in: Presigned url expires in. Only takes effect when outputFormat is storageKey.

Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 30m

save_to_album: Whether to save the screenshot to the device screenshot album

Returns:

ActionScreenshotResponse: The response containing the screenshot data.

Examples:

Take a screenshot and return base64 data: >>> response = action_operator.screenshot()

Take a screenshot and save to file: >>> response = action_operator.screenshot(path=”/path/to/screenshot.png”)

Take a screenshot with specific format: >>> response = action_operator.screenshot(output_format=”base64”)

scroll(*, scroll_x=<gbox_sdk.Omit object>, scroll_y=<gbox_sdk.Omit object>, x=<gbox_sdk.Omit object>, y=<gbox_sdk.Omit object>, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, direction=<gbox_sdk.Omit object>, distance=<gbox_sdk.Omit object>, duration=<gbox_sdk.Omit object>)
Return type:

ActionResult

swipe(*, direction=<gbox_sdk.Omit object>, distance=<gbox_sdk.Omit object>, duration=<gbox_sdk.Omit object>, include_screenshot=<gbox_sdk.Omit object>, location=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, end=<gbox_sdk.Omit object>, start=<gbox_sdk.Omit object>)
Return type:

ActionResult

tap(*, x=<gbox_sdk.Omit object>, y=<gbox_sdk.Omit object>, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>, target=<gbox_sdk.Omit object>)
Return type:

ActionResult

touch(*, points, include_screenshot=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>)

Simulate a touch action on the box.

Return type:

ActionResult

Args:

points: Array of touch points and their actions

include_screenshot: ⚠️ DEPRECATED: Use options.screenshot.phases instead. This field will be

ignored when options.screenshot is provided. Whether to include screenshots in the action response. If false, the screenshot object will still be returned but with empty URIs. Default is false.

options: Action common options

output_format: ⚠️ DEPRECATED: Use options.screenshot.outputFormat instead. Type of the URI.

default is base64. This field will be ignored when options.screenshot is provided.

presigned_expires_in: ⚠️ DEPRECATED: Use options.screenshot.presignedExpiresIn instead. Presigned

url expires in. Only takes effect when outputFormat is storageKey. This field will be ignored when options.screenshot is provided.

Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 30m

screenshot_delay: ⚠️ DEPRECATED: Use options.screenshot.delay instead. This field will be

ignored when options.screenshot is provided.

Delay after performing the action, before taking the final screenshot.

Execution flow:

  1. Take screenshot before action

  2. Perform the action

  3. Wait for screenshotDelay (this parameter)

  4. Take screenshot after action

Example: ‘500ms’ means wait 500ms after the action before capturing the final screenshot.

Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 500ms Maximum allowed: 30s

Returns:

ActionTouchResponse: The response from the touch action.

Example:
>>> response = myBox.action.touch(points=[{"start": {"x": 0, "y": 0}}])
type(text, *, include_screenshot=<gbox_sdk.Omit object>, mode=<gbox_sdk.Omit object>, options=<gbox_sdk.Omit object>, output_format=<gbox_sdk.Omit object>, presigned_expires_in=<gbox_sdk.Omit object>, press_enter=<gbox_sdk.Omit object>, screenshot_delay=<gbox_sdk.Omit object>)

Simulate typing text on the box.

Return type:

ActionResult

Args:

text: Text to type

include_screenshot: ⚠️ DEPRECATED: Use options.screenshot.phases instead. This field will be

ignored when options.screenshot is provided. Whether to include screenshots in the action response. If false, the screenshot object will still be returned but with empty URIs. Default is false.

mode: Text input mode: ‘append’ to add text to existing content, ‘replace’ to replace

all existing text

options: Action common options

output_format: ⚠️ DEPRECATED: Use options.screenshot.outputFormat instead. Type of the URI.

default is base64. This field will be ignored when options.screenshot is provided.

presigned_expires_in: ⚠️ DEPRECATED: Use options.screenshot.presignedExpiresIn instead. Presigned

url expires in. Only takes effect when outputFormat is storageKey. This field will be ignored when options.screenshot is provided.

Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 30m

press_enter: Whether to press Enter after typing the text

screenshot_delay: ⚠️ DEPRECATED: Use options.screenshot.delay instead. This field will be

ignored when options.screenshot is provided.

Delay after performing the action, before taking the final screenshot.

Execution flow:

  1. Take screenshot before action

  2. Perform the action

  3. Wait for screenshotDelay (this parameter)

  4. Take screenshot after action

Example: ‘500ms’ means wait 500ms after the action before capturing the final screenshot.

Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 500ms Maximum allowed: 30s

Returns:

ActionTypeResponse: The response from the type action.

Example:
>>> response = myBox.action.type(text="Hello, World!")
update_settings(scale)

Update the box action settings

Return type:

ActionSettingsUpdateResponse

Args:
scale: The scale of the action to be performed. Must be greater than 0.1 and less than

or equal to 1.

Notes:

  • Scale does not change the box’s actual screen resolution.

  • It affects the size of the output screenshot and the coordinates/distances of actions. Coordinates and distances are scaled by this factor. Example: when scale = 1, Click({x:100, y:100}); when scale = 0.5, the equivalent position is Click({x:50, y:50}).

Returns:

ActionSettingsUpdateResponse: The response from the box action settings update.

Example:
>>> response = myBox.action.update_settings(scale=0.5)
class gbox_sdk.wrapper.box.ActionScreenshot

Bases: ActionScreenshotParams

Extends ActionScreenshotParams to optionally include a file path for saving the screenshot.

Attributes:

path (Optional[str]): The file path where the screenshot will be saved.

clip: Clip
output_format: Annotated[Literal['base64', 'storageKey']]
path: Optional[str]
presigned_expires_in: Annotated[str]
save_to_album: Annotated[bool]
scroll_capture: Annotated[ScrollCapture]
class gbox_sdk.wrapper.box.AndroidAppOperator(client, box, data)

Bases: object

Operator class for managing a specific Android app within a box.

Provides methods to open, restart, close, list activities, and backup the app.

Attributes:

client (GboxClient): The API client used for communication. box (AndroidBox): The Android box data object. data (AndroidApp): The app data object.

backup()

Backup the app.

Return type:

BinaryAPIResponse

Returns:

BinaryAPIResponse: The backup response containing binary data.

Examples:
>>> box.app.backup()
close()

Close the app.

Return type:

None

Examples:
>>> box.app.close()
list_activities()

List all activities of the app.

Return type:

AndroidListActivitiesResponse

Returns:

AndroidListActivitiesResponse: The response containing the list of activities.

Examples:
>>> box.app.list_activities()
open(activity_name=<gbox_sdk.Omit object>)

Open the app, optionally specifying an activity name.

Return type:

None

Args:

activity_name: Activity name, default is the main activity.

Examples:
>>> box.app.open()
>>> box.app.open("com.example.app.MainActivity")
restart(activity_name=<gbox_sdk.Omit object>)

Restart the app, optionally specifying an activity name.

Return type:

None

Args:

activity_name: Activity name, default is the main activity.

Examples:
>>> box.app.restart()
>>> box.app.restart("com.example.app.MainActivity")
class gbox_sdk.wrapper.box.AndroidBoxOperator(client, data)

Bases: BaseBox

Operator class for managing Android boxes, providing access to app and package management functionalities.

Attributes:

app (AndroidAppManager): Manager for Android app operations. pkg (AndroidPkgManager): Manager for Android package operations.

get_connect_address()

Get the connect address for the Android box.

Return type:

AndroidGetConnectAddressResponse

Returns:

AndroidGetConnectAddressResponse: The connect address for the Android box.

class gbox_sdk.wrapper.box.AndroidPkgOperator(client, box, data)

Bases: object

Operator class for managing a specific Android package within a box.

Provides methods to open, close, restart, list activities, and backup the package.

Attributes:

client (GboxClient): The API client used for communication. box (AndroidBox): The Android box data object. data (AndroidGetResponse): The package data object.

backup()

Backup the package.

Return type:

BinaryAPIResponse

Returns:

BinaryAPIResponse: The backup response containing binary data.

Examples:
>>> box.pkg.backup()
close()

Close the package.

Return type:

None

list_activities()

List all activities of the package.

Return type:

AndroidListActivitiesResponse

Returns:

AndroidListActivitiesResponse: The response containing the list of activities.

Examples:
>>> box.pkg.list_activities()
open(activity_name=None)

Open the package, optionally specifying an activity name.

Return type:

None

Args:

activity_name: Activity name, default is the main activity.

Examples:
>>> box.pkg.open()
>>> box.pkg.open("com.example.app.MainActivity")
restart(activity_name=None)

Restart the package, optionally specifying an activity name.

Return type:

None

Args:

activity_name: Activity name, default is the main activity.

Examples:
>>> box.pkg.restart()
>>> box.pkg.restart("com.example.app.MainActivity")
class gbox_sdk.wrapper.box.BaseBox(client, data)

Bases: object

Base class for box operations, providing common interfaces for box lifecycle and actions.

Attributes:

client (GboxClient): The Gbox client instance used for API calls. data (Union[LinuxBox, AndroidBox]): The box data object. action (ActionOperator): Operator for box actions. fs (FileSystemOperator): Operator for file system actions. browser (BrowserOperator): Operator for browser actions.

command(command, on_stdout=None, on_stderr=None, envs=<gbox_sdk.Omit object>, timeout=<gbox_sdk.Omit object>, working_dir=<gbox_sdk.Omit object>)

Execute shell commands in the box.

Return type:

Union[BoxExecuteCommandsResponse, WebSocketResult]

Args:

command: The command to run. Can be a single string or an array of strings

envs: The environment variables to run the command

timeout: The timeout of the command. If the command times out, the exit code will be 124.

For example: ‘timeout 5s sleep 10s’ will result in exit code 124.

Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 30s

working_dir: The working directory of the command. It not provided, the command will be run

in the box.config.workingDir directory.

on_stdout: Callback for stdout.

on_stderr: Callback for stderr.

Returns:

Union[BoxExecuteCommandsResponse, WebSocketResult]: The response containing the command execution result.

Example:
>>> box.command(commands="ls -l", on_stdout=lambda x: print(x), on_stderr=lambda x: print(x))
display()

Retrieve the current display properties for a running box.

This endpoint provides details about the box’s screen resolution, orientation, and other visual properties

Return type:

BoxDisplayResponse

Returns:

BoxDisplayResponse: The response containing the display properties.

Example:
>>> box.display()
live_view(*, expires_in=<gbox_sdk.Omit object>)

Get the live view URL for the box.

Return type:

BoxLiveViewURLResponse

Args:

expires_in: The duration for the live view URL to be valid.

Returns:

BoxLiveViewURLResponse: The response containing the live view URL.

run_code(code, argv=<gbox_sdk.Omit object>, envs=<gbox_sdk.Omit object>, language=<gbox_sdk.Omit object>, timeout=<gbox_sdk.Omit object>, working_dir=<gbox_sdk.Omit object>, on_stdout=None, on_stderr=None)

Run code in the box.

Return type:

Union[BoxRunCodeResponse, WebSocketResult]

Args:

code: The code to run

argv: The arguments to run the code. For example, if you want to run “python index.py

–help”, you should pass [”–help”] as arguments.

envs: The environment variables to run the code

language: The language of the code.

timeout: The timeout of the code execution. If the code execution times out, the exit

code will be 124.

Supported time units: ms (milliseconds), s (seconds), m (minutes), h (hours) Example formats: “500ms”, “30s”, “5m”, “1h” Default: 30s

working_dir: The working directory of the code. It not provided, the code will be run in the

box.config.workingDir directory.

on_stdout: Callback for stdout.

on_stderr: Callback for stderr.

Returns:

Union[BoxRunCodeResponse, WebSocketResult]: The response containing the code execution result.

Example:
>>> box.run_code(
...     code="print('Hello, World!')",
...     language="python",
...     on_stdout=lambda x: print(x),
...     on_stderr=lambda x: print(x),
... )
start(*, wait=<gbox_sdk.Omit object>)

Start the box.

Return type:

Self

Args:

wait: Whether to wait for the box to start.

Returns:

Self: The updated box instance for method chaining.

Example:
>>> box.start()
>>> box.start(wait=True)
stop(*, wait=<gbox_sdk.Omit object>)

Stop the box.

Return type:

Self

Args:

wait: Whether to wait for the box to stop.

Returns:

Self: The updated box instance for method chaining.

Example:
>>> box.stop()
>>> box.stop(wait=True)
terminate(*, wait=<gbox_sdk.Omit object>)

Terminate the box.

Return type:

Self

Args:

wait: Whether to wait for the box to terminate.

Returns:

Self: The updated box instance for method chaining.

Example:
>>> box.terminate()
>>> box.terminate(wait=True)
web_terminal(*, expires_in=<gbox_sdk.Omit object>)

Get the web terminal URL for the box.

Return type:

BoxWebTerminalURLResponse

Args:

body (BoxWebTerminalURLParams): Parameters for web terminal URL.

Returns:

BoxWebTerminalURLResponse: The response containing the web terminal URL.

class gbox_sdk.wrapper.box.BrowserOperator(client, box_id)

Bases: object

Provides operations related to browser management for a specific box.

Args:

client (GboxClient): The GboxClient instance used to interact with the API. box_id (str): The unique identifier of the box.

cdp_url()

Get the Chrome DevTools Protocol (CDP) URL for the browser in the specified box.

Return type:

str

Returns:

str: The CDP URL for the browser.

Example:
>>> box.browser.cdp_url()
close_tab(tab_id)

Close a specific browser tab identified by its id.

This endpoint will permanently close the tab and free up the associated resources. After closing a tab, the ids of subsequent tabs may change.

Return type:

BrowserCloseTabResponse

Args:

tab_id: The tab id

Example:
>>> box.browser.close_tab("1")
list_tab_info()

Retrieve a comprehensive list of all currently open browser tabs in the specified box. This endpoint returns detailed information about each tab including its id, title, current URL, and favicon. The returned id can be used for subsequent operations like navigation, closing, or updating tabs. This is essential for managing multiple browser sessions and understanding the current state of the browser environment.

Return type:

BrowserGetTabsResponse

Returns:

BrowserGetTabsResponse: The list of tab information.

Example:
>>> box.browser.list_tab_info()
list_tabs()

Retrieve a comprehensive list of all currently open browser tabs in the specified box. This endpoint returns detailed information about each tab including its id, title, current URL, and favicon. The returned id can be used for subsequent operations like navigation, closing, or updating tabs. This is essential for managing multiple browser sessions and understanding the current state of the browser environment.

Return type:

List[BrowserTabOperator]

Returns:

list: A list of tab objects. BrowserTabOperator

Example:
>>> box.browser.list_tabs()
open_tab(url)

Create and open a new browser tab with the specified URL.

This endpoint will navigate to the provided URL and return the new tab’s information including its assigned id, loaded title, final URL (after any redirects), and favicon. The returned tab id can be used for future operations on this specific tab. The browser will attempt to load the page and will wait for the DOM content to be loaded before returning the response. If the URL is invalid or unreachable, an error will be returned.

Return type:

BrowserOpenTabResponse

Args:

url: The tab url

Example:
>>> box.browser.open_tab("https://www.google.com")
switch_tab(tab_id)

Switch to a specific browser tab by bringing it to the foreground (making it the active/frontmost tab). This operation sets the specified tab as the currently active tab without changing its URL or content. The tab will receive focus and become visible to the user. This is useful for managing multiple browser sessions and controlling which tab is currently in focus.

Return type:

BrowserSwitchTabResponse

Args:

tab_id: The tab id

Example:
>>> box.browser.switch_tab("1")
update_tab(*, tab_id, url)

Navigate an existing browser tab to a new URL.

This endpoint updates the specified tab by navigating it to the provided URL and returns the updated tab information. The browser will wait for the DOM content to be loaded before returning the response. If the navigation fails due to an invalid URL or network issues, an error will be returned. The updated tab information will include the new title, final URL (after any redirects), and favicon from the new page.

Return type:

BrowserUpdateTabResponse

Args:

tab_id: The tab id url: The tab new url

Example:
>>> box.browser.update_tab(tab_id="1", url="https://www.google.com")
class gbox_sdk.wrapper.box.DirectoryOperator(client, box_id, data)

Bases: object

Operator for directory operations within a box.

Provides methods to list and rename a directory.

Args:

client (GboxClient): The Gbox client instance. box_id (str): The ID of the box to operate on. data (DataDir): The directory data.

list(*, depth=<gbox_sdk.Omit object>, working_dir=<gbox_sdk.Omit object>)

List files and directories in this directory, returning operator objects.

Return type:

List[Union[FileOperator, DirectoryOperator]]

Args:

path: Target directory path in the box

depth: Depth of the directory

working_dir: Working directory. If not provided, the file will be read from the

box.config.workingDir directory.

Returns:

List[Union[FileOperator, DirectoryOperator]]: List of file or directory operator objects.

Example:
>>> box.file_system.list(path="/path/to/directory", depth=1, working_dir="/path/to/working_dir")
>>> box.file_system.list("/path/to/directory")
list_info(*, depth=<gbox_sdk.Omit object>, working_dir=<gbox_sdk.Omit object>)

Get detailed information about files and directories in this directory.

Return type:

FListResponse

Args:

path: Target directory path in the box

depth: Depth of the directory

working_dir: Working directory. If not provided, the file will be read from the

box.config.workingDir directory.

Returns:

FListResponse: The response containing file/directory information.

Example:
>>> box.file_system.list_info(path="/path/to/directory", depth=1, working_dir="/path/to/working_dir")
>>> box.file_system.list_info("/path/to/directory")
rename(*, new_path, working_dir=<gbox_sdk.Omit object>)

Rename this directory.

Return type:

Union[File, Dir]

Args:
new_path: New path in the box. If the path does not start with ‘/’, the file/directory

will be renamed relative to the working directory. If the newPath already exists, the rename will fail.

working_dir: Working directory. If not provided, the file will be read from the

box.config.workingDir directory.

Returns:

FRenameResponse: The response after renaming.

Example:
>>> box.file_system.rename(
...     old_path="/path/to/old/file", new_path="/path/to/new/file", working_dir="/path/to/working_dir"
... )
>>> box.file_system.rename("/path/to/old/file", "/path/to/new/file")
class gbox_sdk.wrapper.box.FileOperator(client, box_id, data)

Bases: object

Operator for file operations within a box.

Provides methods to read, write, and rename a file.

Args:

client (GboxClient): The Gbox client instance. box_id (str): The ID of the box to operate on. data (DataFile): The file data.

read(*, working_dir=<gbox_sdk.Omit object>)

Read the content of this file.

Return type:

FReadResponse

Args:

working_dir: The working directory to read the file from.

Returns:

FReadResponse: The response containing file content.

Example:
>>> box.file_system.read(working_dir="/path/to/working_dir")
>>> box.file_system.read()
rename(new_path, *, working_dir=<gbox_sdk.Omit object>)

Rename this file.

Return type:

Union[File, Dir]

Args:

new_path: The new path of the file. working_dir: The working directory to rename the file in.

Returns:

FRenameResponse: The response after renaming.

Example:
>>> box.file_system.rename(new_path="/path/to/new/file", working_dir="/path/to/working_dir")
write(content, *, working_dir=<gbox_sdk.Omit object>)

Write content to this file (text or binary).

Return type:

File

Args:

content: The content to write to the file. working_dir: The working directory to write the file to.

Returns:

FWriteResponse: The response after writing.

Example:
>>> box.file_system.write(content="Hello, World!", path="/path/to/file", working_dir="/path/to/working_dir")
>>> box.file_system.write("Hello, World!")
class gbox_sdk.wrapper.box.FileSystemOperator(client, box_id)

Bases: object

Operator for file system operations within a box.

Provides methods to list, read, write, remove, check existence, rename, and retrieve file or directory information in a box.

Args:

client (GboxClient): The Gbox client instance. box_id (str): The ID of the box to operate on.

exists(path, *, working_dir=<gbox_sdk.Omit object>)

Check if a file or directory exists.

Return type:

Union[ExistsFileResult, NotExistsFileResult]

Args:
path: Target path in the box. If the path does not start with ‘/’, the file/directory

will be checked relative to the working directory

working_dir: Working directory. If not provided, the file will be read from the

box.config.workingDir directory.

Returns:

FExistsResponse: The response indicating existence.

Example:
>>> box.file_system.exists(path="/path/to/file", working_dir="/path/to/working_dir")
>>> box.file_system.exists("/path/to/file")
get(path, *, working_dir=<gbox_sdk.Omit object>)

Get an operator for a file or directory by its information.

Return type:

Union[FileOperator, DirectoryOperator]

Args:
path: Target path in the box. If the path does not start with ‘/’, the file/directory

will be checked relative to the working directory

working_dir: Working directory. If not provided, the file will be read from the

box.config.workingDir directory.

Returns:

Union[FileOperator, DirectoryOperator]: The corresponding operator object.

Example:
>>> box.file_system.get(path="/path/to/file", working_dir="/path/to/working_dir")
>>> box.file_system.get("/path/to/file")
list(path, *, depth=<gbox_sdk.Omit object>, working_dir=<gbox_sdk.Omit object>)

List files and directories at a given path or with given parameters, returning operator objects.

Return type:

List[Union[FileOperator, DirectoryOperator]]

Args:

path: Target directory path in the box

depth: Depth of the directory

working_dir: Working directory. If not provided, the file will be read from the

box.config.workingDir directory.

Returns:

List[Union[FileOperator, DirectoryOperator]]: List of file or directory operator objects.

Example:
>>> box.file_system.list(path="/path/to/directory", depth=1, working_dir="/path/to/working_dir")
>>> box.file_system.list("/path/to/directory")
list_info(path, *, depth=<gbox_sdk.Omit object>, working_dir=<gbox_sdk.Omit object>)

Get detailed information about files and directories at a given path or with given parameters.

Return type:

FListResponse

Args:

path: Target directory path in the box

depth: Depth of the directory

working_dir: Working directory. If not provided, the file will be read from the

box.config.workingDir directory.

Returns:

FListResponse: The response containing file/directory information.

Example:
>>> box.file_system.list_info(path="/path/to/directory", depth=1, working_dir="/path/to/working_dir")
>>> box.file_system.list_info("/path/to/directory")
read(path, *, working_dir=<gbox_sdk.Omit object>)

Read the content of a file.

Return type:

FReadResponse

Args:
path: Target path in the box. If the path does not start with ‘/’, the file will be

read from the working directory.

working_dir: Working directory. If not provided, the file will be read from the

box.config.workingDir directory.

Returns:

FReadResponse: The response containing file content.

Example:
>>> box.file_system.read(path="/path/to/file", working_dir="/path/to/working_dir")
>>> box.file_system.read("/path/to/file")
remove(path, *, working_dir=<gbox_sdk.Omit object>)

Remove a file or directory.

Return type:

FRemoveResponse

Args:
path: Target path in the box. If the path does not start with ‘/’, the file/directory

will be checked relative to the working directory

working_dir: Working directory. If not provided, the file will be read from the

box.config.workingDir directory.

Returns:

FRemoveResponse: The response after removing the file or directory.

Example:
>>> box.file_system.remove(path="/path/to/file", working_dir="/path/to/working_dir")
>>> box.file_system.remove("/path/to/file")
rename(*, old_path, new_path, working_dir=<gbox_sdk.Omit object>)

Rename a file or directory.

Return type:

Union[File, Dir]

Args:
new_path: New path in the box. If the path does not start with ‘/’, the file/directory

will be renamed relative to the working directory. If the newPath already exists, the rename will fail.

old_path: Old path in the box. If the path does not start with ‘/’, the file/directory

will be renamed relative to the working directory. If the oldPath does not exist, the rename will fail.

working_dir: Working directory. If not provided, the file will be read from the

box.config.workingDir directory.

Returns:

FRenameResponse: The response after renaming.

Example:
>>> box.file_system.rename(
...     old_path="/path/to/old/file", new_path="/path/to/new/file", working_dir="/path/to/working_dir"
... )
write(*, content, path, working_dir=<gbox_sdk.Omit object>)

Write content to a file (text or binary).

Return type:

FileOperator

Args:

content: Content of the file (Max size: 512MB)

path: Target path in the box. If the path does not start with ‘/’, the file will be

written relative to the working directory. Creates necessary directories in the path if they don’t exist. If the target path already exists, the write will fail.

working_dir: Working directory. If not provided, the file will be read from the

box.config.workingDir directory.

Returns:

FileOperator: The file operator for the written file.

Example:
>>> box.file_system.write(content="Hello, World!", path="/path/to/file", working_dir="/path/to/working_dir")
>>> box.file_system.write(content="Hello, World!", path="/path/to/file")
class gbox_sdk.wrapper.box.LinuxBoxOperator(client, data)

Bases: BaseBox

Operator class for managing Linux boxes via the Gbox SDK. Provides an interface to interact with and control Linux-based boxes.