Sandbox
class Sandbox(SandboxBase)
create
@classmethod
def create(cls,
template: Optional[str] = None,
resolution: Optional[Tuple[int, int]] = None,
dpi: Optional[int] = None,
display: Optional[str] = None,
timeout: Optional[int] = None,
metadata: Optional[Dict[str, str]] = None,
envs: Optional[Dict[str, str]] = None,
secure: bool = True,
allow_internet_access: bool = True,
**opts: Unpack[ApiParams]) -> Self
Create a new sandbox.
By default, the sandbox is created from the default desktop sandbox template.
Arguments:
template: Sandbox template name or IDresolution: Startup the desktop with custom screen resolution. Defaults to (1024, 768)dpi: Startup the desktop with custom DPI. Defaults to 96display: Startup the desktop with custom display. Defaults to ":0"timeout: Timeout for the sandbox in seconds, default to 300 seconds. The maximum time a sandbox can be kept alive is 24 hours (86_400 seconds) for Pro users and 1 hour (3_600 seconds) for Hobby users.metadata: Custom metadata for the sandboxenvs: Custom environment variables for the sandboxsecure: Envd is secured with access token and cannot be used without itallow_internet_access: Allow sandbox to access the internet, defaults toTrue.
Returns:
A Sandbox instance for the new sandbox Use this method instead of using the constructor to create a new sandbox.
beta_create
@classmethod
def beta_create(cls,
template: Optional[str] = None,
resolution: Optional[Tuple[int, int]] = None,
dpi: Optional[int] = None,
display: Optional[str] = None,
timeout: Optional[int] = None,
auto_pause: Optional[bool] = False,
metadata: Optional[Dict[str, str]] = None,
envs: Optional[Dict[str, str]] = None,
secure: bool = True,
allow_internet_access: bool = True,
**opts: Unpack[ApiParams]) -> Self
[BETA] This feature is in beta and may change in the future.
Create a new sandbox.
By default, the sandbox is created from the default desktop sandbox template.
Arguments:
template: Sandbox template name or IDresolution: Startup the desktop with custom screen resolution. Defaults to (1024, 768)dpi: Startup the desktop with custom DPI. Defaults to 96display: Startup the desktop with custom display. Defaults to ":0"timeout: Timeout for the sandbox in seconds, default to 300 seconds. The maximum time a sandbox can be kept alive is 24 hours (86_400 seconds) for Pro users and 1 hour (3_600 seconds) for Hobby users.auto_pause: Automatically pause the sandbox after the timeout expires. Defaults toFalse.metadata: Custom metadata for the sandboxenvs: Custom environment variables for the sandboxsecure: Envd is secured with access token and cannot be used without itallow_internet_access: Allow sandbox to access the internet, defaults toTrue.
Returns:
A Sandbox instance for the new sandbox Use this method instead of using the constructor to create a new sandbox.
screenshot
@overload
def screenshot(format: Literal["stream"]) -> Iterator[bytes]
Take a screenshot and return it as a stream of bytes.
screenshot
@overload
def screenshot(format: Literal["bytes"]) -> bytearray
Take a screenshot and return it as a bytearray.
screenshot
def screenshot(format: Literal["bytes", "stream"] = "bytes")
Take a screenshot and return it in the specified format.
Arguments:
format: The format of the screenshot. Can be 'bytes', 'blob', or 'stream'.
Returns:
The screenshot in the specified format.
left_click
def left_click(x: Optional[int] = None, y: Optional[int] = None)
Left click on the mouse position.
double_click
def double_click(x: Optional[int] = None, y: Optional[int] = None)
Double left click on the mouse position.
middle_click
def middle_click(x: Optional[int] = None, y: Optional[int] = None)
Middle click on the mouse position.
scroll
def scroll(direction: Literal["up", "down"] = "down", amount: int = 1)
Scroll the mouse wheel by the given amount.
Arguments:
direction: The direction to scroll. Can be "up" or "down".amount: The amount to scroll.
move_mouse
def move_mouse(x: int, y: int)
Move the mouse to the given coordinates.
Arguments:
x: The x coordinate.y: The y coordinate.
mouse_press
def mouse_press(button: Literal["left", "right", "middle"] = "left")
Press the mouse button.
mouse_release
def mouse_release(button: Literal["left", "right", "middle"] = "left")
Release the mouse button.
get_cursor_position
def get_cursor_position() -> tuple[int, int]
Get the current cursor position.
Raises:
RuntimeError: If the cursor position cannot be determined
Returns:
A tuple with the x and y coordinates
get_screen_size
def get_screen_size() -> tuple[int, int]
Get the current screen size.
Raises:
RuntimeError: If the screen size cannot be determined
Returns:
A tuple with the width and height
write
def write(text: str, *, chunk_size: int = 25, delay_in_ms: int = 75) -> None
Write the given text at the current cursor position.
Arguments:
text: The text to write.chunk_size: The size of each chunk of text to write.delay_in_ms: The delay between each chunk of text.
press
def press(key: Union[str, list[str]])
Press a key.
Arguments:
key: The key to press (e.g. "enter", "space", "backspace", etc.).
drag
def drag(fr: tuple[int, int], to: tuple[int, int])
Drag the mouse from the given position to the given position.
Arguments:
from: The starting position.to: The ending position.
wait
def wait(ms: int)
Wait for the given amount of time.
Arguments:
ms: The amount of time to wait in milliseconds.
open
def open(file_or_url: str)
Open a file or a URL in the default application.
Arguments:
file_or_url: The file or URL to open.
get_current_window_id
def get_current_window_id() -> str
Get the current window ID.
get_application_windows
def get_application_windows(application: str) -> list[str]
Get the window IDs of all windows for the given application.
get_window_title
def get_window_title(window_id: str) -> str
Get the title of the window with the given ID.
launch
def launch(application: str, uri: Optional[str] = None)
Launch an application.