boxfab-desktop 0.1.0a1__tar.gz

boxfab_desktop-0.1.0a1/LICENSE

@@ -0,0 +1,10 @@
+MIT License
+
+Copyright (c) 2025 FOUNDRYLABS, INC.
+Copyright (c) 2026 ContextFab, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

boxfab_desktop-0.1.0a1/PKG-INFO

@@ -0,0 +1,290 @@
+Metadata-Version: 2.4
+Name: boxfab-desktop
+Version: 0.1.0a1
+Summary: BoxFab Desktop: a virtual Linux desktop in a BoxFab sandbox, for computer-use agents
+Author: ContextFab, Inc.
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: boxfab>=0.1.0a3,<0.2
+Requires-Dist: requests>=2.32.3,<3
+Requires-Dist: urllib3>=2.8.0,<3
+Requires-Dist: pillow>=13.0.0,<14
+Requires-Python: >=3.11
+Project-URL: Repository, https://github.com/boxfab/python-sdk
+Description-Content-Type: text/markdown
+
+# BoxFab Desktop (Python)
+
+A virtual Linux desktop in a [BoxFab](https://boxfab.io) sandbox, for computer-use agents: mouse
+and keyboard control, screenshots, application windows, and a live stream of the screen in the
+browser.
+
+## Getting started
+
+### 1. Get a BoxFab API key
+
+Get a key from the [BoxFab dashboard](https://dashboard.boxfab.io) and set it as
+`BOXFAB_API_KEY`. The SDK reads only `BOXFAB_*` variables.
+
+### 2. Install the SDK
+
+```bash
+pip install boxfab-desktop
+```
+
+> **Stream access.** `desktop.stream.start()` runs without a password unless you pass
+> `require_auth=True`. The stream URL contains the sandbox ID, and anyone who has the URL can see
+> and control the desktop. Pass `require_auth=True` whenever the URL leaves your backend; the auth
+> key is then part of the URL returned by `get_url(auth_key=...)`, so share that URL only with the
+> intended viewer.
+
+### 3. Create Desktop Sandbox
+
+```python
+from boxfab_desktop import Sandbox
+
+# Create a new desktop sandbox
+desktop = Sandbox.create()
+
+# Launch an application
+desktop.launch('google-chrome')  # or vscode, firefox, etc.
+
+# Wait 10s for the application to open
+desktop.wait(10000)
+
+# Stream the application's window
+# Note: There can be only one stream at a time
+# You need to stop the current stream before streaming another application
+desktop.stream.start(
+    window_id=desktop.get_current_window_id(), # if not provided the whole desktop will be streamed
+    require_auth=True
+)
+
+# Get the stream auth key
+auth_key = desktop.stream.get_auth_key()
+
+# Print the stream URL
+print('Stream URL:', desktop.stream.get_url(auth_key=auth_key))
+
+# Kill the sandbox after the tasks are finished
+# desktop.kill()
+```
+
+### 4. Bind the configuration to a client
+
+The top-level `Sandbox` export reads its configuration from the environment variables. To use an explicit configuration — e.g. several API keys or domains in one process — create a `BoxFab` client and use the resource classes it exposes:
+
+```python
+from boxfab_desktop import BoxFab
+
+client = BoxFab(api_key="e2b_***", domain="boxfab.io")
+
+desktop = client.Sandbox.create()
+desktop.stream.start()
+
+# The core resources are bound to the client's configuration as well.
+volume = client.Volume.create("my-volume")
+exists = client.Template.exists("my-template")
+secret = client.Secret.create("openai-api-key", "sk-***")
+
+# The classes can be assigned and used like the top-level ones.
+Sandbox = client.Sandbox
+paginator = Sandbox.list()
+```
+
+Per-call params still take precedence over the client's params, and clients are isolated from each other and from the env-configured top-level exports.
+
+## Features
+
+### Streaming desktop's screen
+
+```python
+from boxfab_desktop import Sandbox
+desktop = Sandbox.create()
+
+# Start the stream
+desktop.stream.start()
+
+# Get stream URL
+url = desktop.stream.get_url()
+print(url)
+
+# Stop the stream
+desktop.stream.stop()
+```
+
+### Streaming with password protection
+
+```python
+from boxfab_desktop import Sandbox
+desktop = Sandbox.create()
+
+# Start the stream
+desktop.stream.start(
+    require_auth=True  # Enable authentication with an auto-generated key
+)
+
+# Retrieve the authentication key
+auth_key = desktop.stream.get_auth_key()
+
+# Get stream URL
+url = desktop.stream.get_url(auth_key=auth_key)
+print(url)
+
+# Stop the stream
+desktop.stream.stop()
+```
+
+### Streaming specific application
+
+> [!WARNING]
+>
+> - Will raise an error if the desired application is not open yet
+> - The stream will close once the application closes
+> - Creating multiple streams at the same time is not supported, you may have to stop the current stream and start a new one for each application
+
+```python
+from boxfab_desktop import Sandbox
+desktop = Sandbox.create()
+
+# Get current (active) window ID
+window_id = desktop.get_current_window_id()
+
+# Get all windows of the application
+window_ids = desktop.get_application_windows("Firefox")
+
+# Start the stream
+desktop.stream.start(window_id=window_ids[0])
+
+# Stop the stream
+desktop.stream.stop()
+```
+
+### Mouse control
+
+```python
+from boxfab_desktop import Sandbox
+desktop = Sandbox.create()
+
+desktop.double_click()
+desktop.left_click()
+desktop.left_click(x=100, y=200)
+desktop.right_click()
+desktop.right_click(x=100, y=200)
+desktop.middle_click()
+desktop.middle_click(x=100, y=200)
+desktop.scroll(10) # Scroll by the amount. Positive for up, negative for down.
+desktop.move_mouse(100, 200) # Move to x, y coordinates
+desktop.drag((100, 100), (200, 200)) # Drag using the mouse
+desktop.mouse_press("left") # Press the mouse button
+desktop.mouse_release("left") # Release the mouse button
+```
+
+### Keyboard control
+
+```python
+from boxfab_desktop import Sandbox
+desktop = Sandbox.create()
+
+# Write text at the current cursor position with customizable typing speed
+desktop.write("Hello, world!")  # Default: chunk_size=25, delay_in_ms=75
+desktop.write("Fast typing!", chunk_size=50, delay_in_ms=25)  # Faster typing
+
+# Press keys
+desktop.press("enter")
+desktop.press("space")
+desktop.press("backspace")
+desktop.press(["ctrl", "c"]) # Key combination
+```
+
+### Window control
+
+```python
+from boxfab_desktop import Sandbox
+desktop = Sandbox.create()
+
+# Get current (active) window ID
+window_id = desktop.get_current_window_id()
+
+# Get all windows of the application
+window_ids = desktop.get_application_windows("Firefox")
+
+# Get window title
+title = desktop.get_window_title(window_id)
+```
+
+### Screenshot
+
+```python
+from boxfab_desktop import Sandbox
+desktop = Sandbox.create()
+
+# Take a screenshot and save it as "screenshot.png" locally
+image = desktop.screenshot()
+# Save the image to a file
+with open("screenshot.png", "wb") as f:
+    f.write(image)
+```
+
+### Open file
+
+```python
+from boxfab_desktop import Sandbox
+desktop = Sandbox.create()
+
+# Open file with default application
+desktop.files.write("/home/user/index.js", "console.log('hello')") # First create the file
+desktop.open("/home/user/index.js") # Then open it
+```
+
+### Launch applications
+
+```python
+from boxfab_desktop import Sandbox
+desktop = Sandbox.create()
+
+# Launch the application
+desktop.launch('google-chrome')
+```
+
+### Run any bash commands
+
+```python
+from boxfab_desktop import Sandbox
+desktop = Sandbox.create()
+
+# Run any bash command
+out = desktop.commands.run("ls -la /home/user")
+print(out)
+```
+
+### Wait
+
+```python
+from boxfab_desktop import Sandbox
+desktop = Sandbox.create()
+
+desktop.wait(1000) # Wait for 1 second
+```
+
+## Under the hood
+
+The desktop-like environment is based on Linux and [Xfce](https://www.xfce.org/) at the moment. We chose Xfce because it's a fast and lightweight environment that's also popular and actively supported. However, this Sandbox template is fully customizable and you can create your own desktop environment.
+BoxFab's template is in [boxfab/desktop](https://github.com/boxfab/desktop/tree/main/template), generated from [e2b-dev/desktop](https://github.com/e2b-dev/desktop/tree/main/template).
+
+BoxFab sandboxes are [Firecracker](https://firecracker-microvm.github.io/) microVMs, run on the
+open-source [E2B](https://github.com/e2b-dev/infra) sandbox infrastructure. This package is derived
+from the open-source E2B Desktop SDK;
+[UPSTREAM.md](https://github.com/boxfab/python-sdk/blob/main/UPSTREAM.md) lists every change.
+
+## License
+
+MIT, as the E2B Desktop SDK it is derived from; see [LICENSE](LICENSE).
+
+BoxFab is a product of ContextFab, Inc.

boxfab_desktop-0.1.0a1/README.md

@@ -0,0 +1,269 @@
+# BoxFab Desktop (Python)
+
+A virtual Linux desktop in a [BoxFab](https://boxfab.io) sandbox, for computer-use agents: mouse
+and keyboard control, screenshots, application windows, and a live stream of the screen in the
+browser.
+
+## Getting started
+
+### 1. Get a BoxFab API key
+
+Get a key from the [BoxFab dashboard](https://dashboard.boxfab.io) and set it as
+`BOXFAB_API_KEY`. The SDK reads only `BOXFAB_*` variables.
+
+### 2. Install the SDK
+
+```bash
+pip install boxfab-desktop
+```
+
+> **Stream access.** `desktop.stream.start()` runs without a password unless you pass
+> `require_auth=True`. The stream URL contains the sandbox ID, and anyone who has the URL can see
+> and control the desktop. Pass `require_auth=True` whenever the URL leaves your backend; the auth
+> key is then part of the URL returned by `get_url(auth_key=...)`, so share that URL only with the
+> intended viewer.
+
+### 3. Create Desktop Sandbox
+
+```python
+from boxfab_desktop import Sandbox
+
+# Create a new desktop sandbox
+desktop = Sandbox.create()
+
+# Launch an application
+desktop.launch('google-chrome')  # or vscode, firefox, etc.
+
+# Wait 10s for the application to open
+desktop.wait(10000)
+
+# Stream the application's window
+# Note: There can be only one stream at a time
+# You need to stop the current stream before streaming another application
+desktop.stream.start(
+    window_id=desktop.get_current_window_id(), # if not provided the whole desktop will be streamed
+    require_auth=True
+)
+
+# Get the stream auth key
+auth_key = desktop.stream.get_auth_key()
+
+# Print the stream URL
+print('Stream URL:', desktop.stream.get_url(auth_key=auth_key))
+
+# Kill the sandbox after the tasks are finished
+# desktop.kill()
+```
+
+### 4. Bind the configuration to a client
+
+The top-level `Sandbox` export reads its configuration from the environment variables. To use an explicit configuration — e.g. several API keys or domains in one process — create a `BoxFab` client and use the resource classes it exposes:
+
+```python
+from boxfab_desktop import BoxFab
+
+client = BoxFab(api_key="e2b_***", domain="boxfab.io")
+
+desktop = client.Sandbox.create()
+desktop.stream.start()
+
+# The core resources are bound to the client's configuration as well.
+volume = client.Volume.create("my-volume")
+exists = client.Template.exists("my-template")
+secret = client.Secret.create("openai-api-key", "sk-***")
+
+# The classes can be assigned and used like the top-level ones.
+Sandbox = client.Sandbox
+paginator = Sandbox.list()
+```
+
+Per-call params still take precedence over the client's params, and clients are isolated from each other and from the env-configured top-level exports.
+
+## Features
+
+### Streaming desktop's screen
+
+```python
+from boxfab_desktop import Sandbox
+desktop = Sandbox.create()
+
+# Start the stream
+desktop.stream.start()
+
+# Get stream URL
+url = desktop.stream.get_url()
+print(url)
+
+# Stop the stream
+desktop.stream.stop()
+```
+
+### Streaming with password protection
+
+```python
+from boxfab_desktop import Sandbox
+desktop = Sandbox.create()
+
+# Start the stream
+desktop.stream.start(
+    require_auth=True  # Enable authentication with an auto-generated key
+)
+
+# Retrieve the authentication key
+auth_key = desktop.stream.get_auth_key()
+
+# Get stream URL
+url = desktop.stream.get_url(auth_key=auth_key)
+print(url)
+
+# Stop the stream
+desktop.stream.stop()
+```
+
+### Streaming specific application
+
+> [!WARNING]
+>
+> - Will raise an error if the desired application is not open yet
+> - The stream will close once the application closes
+> - Creating multiple streams at the same time is not supported, you may have to stop the current stream and start a new one for each application
+
+```python
+from boxfab_desktop import Sandbox
+desktop = Sandbox.create()
+
+# Get current (active) window ID
+window_id = desktop.get_current_window_id()
+
+# Get all windows of the application
+window_ids = desktop.get_application_windows("Firefox")
+
+# Start the stream
+desktop.stream.start(window_id=window_ids[0])
+
+# Stop the stream
+desktop.stream.stop()
+```
+
+### Mouse control
+
+```python
+from boxfab_desktop import Sandbox
+desktop = Sandbox.create()
+
+desktop.double_click()
+desktop.left_click()
+desktop.left_click(x=100, y=200)
+desktop.right_click()
+desktop.right_click(x=100, y=200)
+desktop.middle_click()
+desktop.middle_click(x=100, y=200)
+desktop.scroll(10) # Scroll by the amount. Positive for up, negative for down.
+desktop.move_mouse(100, 200) # Move to x, y coordinates
+desktop.drag((100, 100), (200, 200)) # Drag using the mouse
+desktop.mouse_press("left") # Press the mouse button
+desktop.mouse_release("left") # Release the mouse button
+```
+
+### Keyboard control
+
+```python
+from boxfab_desktop import Sandbox
+desktop = Sandbox.create()
+
+# Write text at the current cursor position with customizable typing speed
+desktop.write("Hello, world!")  # Default: chunk_size=25, delay_in_ms=75
+desktop.write("Fast typing!", chunk_size=50, delay_in_ms=25)  # Faster typing
+
+# Press keys
+desktop.press("enter")
+desktop.press("space")
+desktop.press("backspace")
+desktop.press(["ctrl", "c"]) # Key combination
+```
+
+### Window control
+
+```python
+from boxfab_desktop import Sandbox
+desktop = Sandbox.create()
+
+# Get current (active) window ID
+window_id = desktop.get_current_window_id()
+
+# Get all windows of the application
+window_ids = desktop.get_application_windows("Firefox")
+
+# Get window title
+title = desktop.get_window_title(window_id)
+```
+
+### Screenshot
+
+```python
+from boxfab_desktop import Sandbox
+desktop = Sandbox.create()
+
+# Take a screenshot and save it as "screenshot.png" locally
+image = desktop.screenshot()
+# Save the image to a file
+with open("screenshot.png", "wb") as f:
+    f.write(image)
+```
+
+### Open file
+
+```python
+from boxfab_desktop import Sandbox
+desktop = Sandbox.create()
+
+# Open file with default application
+desktop.files.write("/home/user/index.js", "console.log('hello')") # First create the file
+desktop.open("/home/user/index.js") # Then open it
+```
+
+### Launch applications
+
+```python
+from boxfab_desktop import Sandbox
+desktop = Sandbox.create()
+
+# Launch the application
+desktop.launch('google-chrome')
+```
+
+### Run any bash commands
+
+```python
+from boxfab_desktop import Sandbox
+desktop = Sandbox.create()
+
+# Run any bash command
+out = desktop.commands.run("ls -la /home/user")
+print(out)
+```
+
+### Wait
+
+```python
+from boxfab_desktop import Sandbox
+desktop = Sandbox.create()
+
+desktop.wait(1000) # Wait for 1 second
+```
+
+## Under the hood
+
+The desktop-like environment is based on Linux and [Xfce](https://www.xfce.org/) at the moment. We chose Xfce because it's a fast and lightweight environment that's also popular and actively supported. However, this Sandbox template is fully customizable and you can create your own desktop environment.
+BoxFab's template is in [boxfab/desktop](https://github.com/boxfab/desktop/tree/main/template), generated from [e2b-dev/desktop](https://github.com/e2b-dev/desktop/tree/main/template).
+
+BoxFab sandboxes are [Firecracker](https://firecracker-microvm.github.io/) microVMs, run on the
+open-source [E2B](https://github.com/e2b-dev/infra) sandbox infrastructure. This package is derived
+from the open-source E2B Desktop SDK;
+[UPSTREAM.md](https://github.com/boxfab/python-sdk/blob/main/UPSTREAM.md) lists every change.
+
+## License
+
+MIT, as the E2B Desktop SDK it is derived from; see [LICENSE](LICENSE).
+
+BoxFab is a product of ContextFab, Inc.

boxfab_desktop-0.1.0a1/boxfab_desktop/__init__.py

@@ -0,0 +1,4 @@
+from boxfab import *
+
+from .client import BoxFab, BoxFabClientParams, E2B, E2BClientParams
+from .main import Sandbox

boxfab_desktop-0.1.0a1/boxfab_desktop/client.py

@@ -0,0 +1,91 @@
+from typing import Dict, Type, TypeVar, Unpack, cast
+
+from boxfab import ApiParams, BoxFabClientParams, E2BClientParams
+from boxfab import BoxFab as CoreBoxFab
+from boxfab_desktop.main import Sandbox
+
+T = TypeVar("T")
+
+__all__ = ["BoxFab", "BoxFabClientParams", "E2B", "E2BClientParams"]
+
+
+def _bind(cls: Type[T], api_params: ApiParams) -> Type[T]:
+    """Generate a subclass of ``cls`` carrying ``api_params`` as its bound params."""
+    return cast(
+        Type[T],
+        type(cls.__name__, (cls,), {"_bound_api_params": api_params}),
+    )
+
+
+class BoxFab:
+    """
+    BoxFab client with an explicitly bound connection configuration.
+
+    The resource classes exposed by the client (`Sandbox`, `Volume`,
+    `AsyncVolume`, `Template`, `AsyncTemplate`, `Secret`, `AsyncSecret`) behave
+    exactly like the top-level exports of the same name, except the params
+    passed to the client are used as the defaults instead of the environment
+    variables.
+    Per-call params still take precedence over the client's params.
+
+    Multiple clients are fully isolated from each other and from the top-level
+    env-configured exports.
+
+    Example:
+    ```python
+    from boxfab_desktop import BoxFab
+
+    client = BoxFab(api_key="e2b_...", domain="boxfab.io")
+
+    desktop = client.Sandbox.create()
+    desktop.stream.start()
+    ```
+    """
+
+    def __init__(self, **opts: Unpack[BoxFabClientParams]):
+        """
+        Create a new client with the API params bound to it.
+
+        :param opts: API params used as the defaults for every call made
+            through this client's resource classes.
+        """
+        # Params are copied so later mutations of the caller's dicts cannot
+        # change the bound configuration.
+        api_params = cast(ApiParams, dict(cast(Dict[str, object], opts)))
+
+        headers = api_params.get("headers")
+        if headers is not None:
+            api_params["headers"] = dict(headers)
+
+        api_headers = api_params.get("api_headers")
+        if api_headers is not None:
+            api_params["api_headers"] = dict(api_headers)
+
+        self.Sandbox = _bind(Sandbox, api_params)
+        """Desktop `Sandbox` class bound to this client's connection configuration."""
+
+        # The resources that are not specific to the Desktop are bound by the
+        # core client.
+        core = CoreBoxFab(**api_params)
+
+        self.Volume = core.Volume
+        """`Volume` class bound to this client's connection configuration."""
+
+        self.AsyncVolume = core.AsyncVolume
+        """`AsyncVolume` class bound to this client's connection configuration."""
+
+        self.Template = core.Template
+        """`Template` class bound to this client's connection configuration."""
+
+        self.AsyncTemplate = core.AsyncTemplate
+        """`AsyncTemplate` class bound to this client's connection configuration."""
+
+        self.Secret = core.Secret
+        """`Secret` class bound to this client's connection configuration."""
+
+        self.AsyncSecret = core.AsyncSecret
+        """`AsyncSecret` class bound to this client's connection configuration."""
+
+
+# Upstream name, kept so code written for the upstream package ports by changing only the import.
+E2B = BoxFab

boxfab_desktop-0.1.0a1/boxfab_desktop/main.py

@@ -0,0 +1,585 @@
+import logging
+import time
+from re import search as re_search
+from shlex import quote as quote_string
+from typing import (
+    Callable,
+    Dict,
+    Iterator,
+    Literal,
+    Optional,
+    Self,
+    Unpack,
+    overload,
+    Tuple,
+    Union,
+)
+from uuid import uuid4
+
+from boxfab import (
+    Sandbox as SandboxBase,
+    CommandHandle,
+    CommandResult,
+    TimeoutException,
+    CommandExitException,
+    SandboxIamOpts,
+    SandboxLifecycle,
+    SandboxNetworkOpts,
+    Volume,
+)
+from boxfab.connection_config import ApiParams
+
+MOUSE_BUTTONS = {"left": 1, "right": 3, "middle": 2}
+
+KEYS = {
+    "alt": "Alt_L",
+    "alt_left": "Alt_L",
+    "alt_right": "Alt_R",
+    "backspace": "BackSpace",
+    "break": "Pause",
+    "caps_lock": "Caps_Lock",
+    "cmd": "Super_L",
+    "command": "Super_L",
+    "control": "Control_L",
+    "control_left": "Control_L",
+    "control_right": "Control_R",
+    "ctrl": "Control_L",
+    "del": "Delete",
+    "delete": "Delete",
+    "down": "Down",
+    "end": "End",
+    "enter": "Return",
+    "esc": "Escape",
+    "escape": "Escape",
+    "f1": "F1",
+    "f2": "F2",
+    "f3": "F3",
+    "f4": "F4",
+    "f5": "F5",
+    "f6": "F6",
+    "f7": "F7",
+    "f8": "F8",
+    "f9": "F9",
+    "f10": "F10",
+    "f11": "F11",
+    "f12": "F12",
+    "home": "Home",
+    "insert": "Insert",
+    "left": "Left",
+    "menu": "Menu",
+    "meta": "Meta_L",
+    "num_lock": "Num_Lock",
+    "page_down": "Page_Down",
+    "page_up": "Page_Up",
+    "pause": "Pause",
+    "print": "Print",
+    "right": "Right",
+    "scroll_lock": "Scroll_Lock",
+    "shift": "Shift_L",
+    "shift_left": "Shift_L",
+    "shift_right": "Shift_R",
+    "space": "space",
+    "super": "Super_L",
+    "super_left": "Super_L",
+    "super_right": "Super_R",
+    "tab": "Tab",
+    "up": "Up",
+    "win": "Super_L",
+    "windows": "Super_L",
+}
+
+
+def map_key(key: str) -> str:
+    lower_key = key.lower()
+    if lower_key in KEYS:
+        return KEYS[lower_key]
+    return lower_key
+
+
+class _VNCServer:
+    def __init__(self, desktop: "Sandbox") -> None:
+        self.__novnc_handle: Optional[CommandHandle] = None
+
+        self._vnc_port = 5900
+        self._port = 6080
+        self._novnc_auth_enabled = False
+        self._novnc_password = None
+
+        self._url = f"https://{desktop.get_host(self._port)}/vnc.html"
+
+        self.__desktop = desktop
+
+    def _wait_for_port(self, port: int) -> bool:
+        return self.__desktop._wait_and_verify(
+            f'netstat -tuln | grep ":{port} "', lambda r: r.stdout.strip() != ""
+        )
+
+    def _check_vnc_running(self) -> bool:
+        try:
+            self.__desktop.commands.run("pgrep -x x11vnc")
+            return True
+        except CommandExitException:
+            return False
+
+    @staticmethod
+    def _generate_password(length: int = 16) -> str:
+        import secrets
+        import string
+
+        characters = string.ascii_letters + string.digits
+        return "".join(secrets.choice(characters) for _ in range(length))
+
+    def get_url(
+        self,
+        auto_connect: bool = True,
+        view_only: bool = False,
+        resize: str = "scale",
+        auth_key: Optional[str] = None,
+    ) -> str:
+        params = []
+        if auto_connect:
+            params.append("autoconnect=true")
+        if view_only:
+            params.append("view_only=true")
+        if resize:
+            params.append(f"resize={resize}")
+        if auth_key:
+            params.append(f"password={auth_key}")
+        if params:
+            return f"{self._url}?{'&'.join(params)}"
+        return self._url
+
+    def get_auth_key(self) -> str:
+        if not self._novnc_password:
+            raise RuntimeError(
+                "Unable to retrieve stream auth key, check if require_auth is enabled"
+            )
+        return self._novnc_password
+
+    def start(
+        self,
+        vnc_port: Optional[int] = None,
+        port: Optional[int] = None,
+        require_auth: bool = False,
+        window_id: Optional[str] = None,
+    ) -> None:
+        # If stream is already running, throw an error
+        if self._check_vnc_running():
+            raise RuntimeError("Stream is already running")
+
+        # Update parameters if provided
+        self._vnc_port = vnc_port or self._vnc_port
+        self._port = port or self._port
+        self._novnc_auth_enabled = require_auth or self._novnc_auth_enabled
+        self._novnc_password = self._generate_password() if require_auth else None
+
+        # Update URL with new port
+        self._url = f"https://{self.__desktop.get_host(self._port)}/vnc.html"
+
+        # Set up VNC command
+        pwd_flag = "-nopw"
+        if self._novnc_auth_enabled:
+            self.__desktop.commands.run("mkdir -p ~/.vnc")
+            self.__desktop.commands.run(
+                f"x11vnc -storepasswd {self._novnc_password} ~/.vnc/passwd"
+            )
+            pwd_flag = "-usepw"
+
+        window_id_flag = ""
+        if window_id:
+            window_id_flag = f"-id {window_id}"
+
+        vnc_command = (
+            f"x11vnc -bg -display {self.__desktop._display} -forever -wait 50 -shared "
+            f"-rfbport {self._vnc_port} {pwd_flag} 2>/tmp/x11vnc_stderr.log {window_id_flag}"
+        )
+
+        novnc_command = (
+            f"cd /opt/noVNC/utils && ./novnc_proxy --vnc localhost:{self._vnc_port} "
+            f"--listen {self._port} --web /opt/noVNC > /tmp/novnc.log 2>&1"
+        )
+
+        self.__desktop.commands.run(vnc_command)
+
+        self.__novnc_handle = self.__desktop.commands.run(
+            novnc_command, background=True, timeout=0
+        )
+        if not self._wait_for_port(self._port):
+            raise TimeoutException("Could not start noVNC server")
+
+    def stop(self) -> None:
+        if self._check_vnc_running():
+            self.__desktop.commands.run("pkill x11vnc")
+
+        if self.__novnc_handle:
+            self.__novnc_handle.kill()
+            self.__novnc_handle = None
+
+
+class Sandbox(SandboxBase):
+    default_template = "desktop"
+    __vnc_server: _VNCServer
+    _last_xfce4_pid: Optional[str] = None
+    _display: str
+
+    @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: Optional[bool] = None,
+        allow_internet_access: Optional[bool] = None,
+        network: Optional[SandboxNetworkOpts] = None,
+        iam: Optional[SandboxIamOpts] = None,
+        lifecycle: Optional[SandboxLifecycle] = None,
+        volume_mounts: Optional[Dict[str, Union[Volume, str]]] = None,
+        logger: Optional[logging.Logger] = None,
+        **opts: Unpack[ApiParams],
+    ) -> Self:
+        """
+        Create a new sandbox.
+
+        By default, the sandbox is created from the default `desktop` sandbox template.
+
+
+        :param template: Sandbox template name or ID
+        :param resolution: Startup the desktop with custom screen resolution. Defaults to (1024, 768)
+        :param dpi: Startup the desktop with custom DPI. Defaults to 96
+        :param display: Startup the desktop with custom display. Defaults to ":0"
+        :param 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.
+        :param metadata: Custom metadata for the sandbox
+        :param envs: Custom environment variables for the sandbox
+        :param secure: Deprecated — every sandbox secures envd access; accepted for backward compatibility and ignored
+        :param allow_internet_access: Allow sandbox to access the internet
+
+        :return: A Sandbox instance for the new sandbox
+
+        Use this method instead of using the constructor to create a new sandbox.
+        """
+
+        # Initialize environment variables with DISPLAY
+        display = display or ":0"
+        if envs is None:
+            envs = {}
+        envs["DISPLAY"] = display
+
+        sbx = super().create(
+            template=template,
+            timeout=timeout,
+            metadata=metadata,
+            envs=envs,
+            allow_internet_access=allow_internet_access,
+            network=network,
+            iam=iam,
+            lifecycle=lifecycle,
+            volume_mounts=volume_mounts,
+            logger=logger,
+            **opts,
+        )
+
+        try:
+            sbx._display = display
+            width, height = resolution or (1024, 768)
+            xvfb_handle = sbx.commands.run(
+                f"Xvfb {display} -ac -screen 0 {width}x{height}x24"
+                f" -retro -dpi {dpi or 96} -nolisten tcp -nolisten unix",
+                background=True,
+                timeout=0,
+            )
+            xvfb_handle.disconnect()
+
+            if not sbx._wait_and_verify(
+                f"xdpyinfo -display {display}", lambda r: r.exit_code == 0
+            ):
+                raise TimeoutException("Could not start Xvfb")
+
+            sbx.__vnc_server = _VNCServer(sbx)
+            sbx._start_xfce4()
+        except Exception:
+            try:
+                sbx.kill()
+            except Exception:
+                pass
+            raise
+
+        return sbx
+
+    def _wait_and_verify(
+        self,
+        cmd: str,
+        on_result: Callable[[CommandResult], bool],
+        timeout: int = 10,
+        interval: float = 0.5,
+    ) -> bool:
+        elapsed = 0
+        while elapsed < timeout:
+            try:
+                if on_result(self.commands.run(cmd)):
+                    return True
+            except CommandExitException:
+                pass
+
+            time.sleep(interval)
+            elapsed += interval
+
+        return False
+
+    def _start_xfce4(self):
+        """
+        Start xfce4 session if logged out or not running.
+        """
+        if self._last_xfce4_pid is None or "[xfce4-session] <defunct>" in (
+            self.commands.run(
+                f"ps aux | grep {self._last_xfce4_pid} | grep -v grep | head -n 1"
+            ).stdout.strip()
+        ):
+            xfce4_handle = self.commands.run("startxfce4", background=True, timeout=0)
+            self._last_xfce4_pid = xfce4_handle.pid
+            xfce4_handle.disconnect()
+
+        if not self._wait_and_verify(
+            "pgrep -x xfce4-session >/dev/null && pgrep -x xfwm4 >/dev/null && pgrep -x xfdesktop >/dev/null",
+            lambda r: r.exit_code == 0,
+            60,
+        ):
+            raise TimeoutException("Could not start XFCE")
+
+    @property
+    def stream(self) -> _VNCServer:
+        return self.__vnc_server
+
+    @overload
+    def screenshot(self, format: Literal["stream"]) -> Iterator[bytes]:
+        """
+        Take a screenshot and return it as a stream of bytes.
+        """
+
+    @overload
+    def screenshot(
+        self,
+        format: Literal["bytes"] = "bytes",
+    ) -> bytearray:
+        """
+        Take a screenshot and return it as a bytearray.
+        """
+
+    def screenshot(
+        self,
+        format: Literal["bytes", "stream"] = "bytes",
+    ):
+        """
+        Take a screenshot and return it in the specified format.
+
+        :param format: The format of the screenshot. Can be 'bytes', 'blob', or 'stream'.
+        :returns: The screenshot in the specified format.
+        """
+        screenshot_path = f"/tmp/screenshot-{uuid4()}.png"
+
+        self.commands.run(f"scrot --pointer {screenshot_path}")
+
+        file = self.files.read(screenshot_path, format=format)
+        self.files.remove(screenshot_path)
+        return file
+
+    def left_click(self, x: Optional[int] = None, y: Optional[int] = None):
+        """
+        Left click on the mouse position.
+        """
+        if x and y:
+            self.move_mouse(x, y)
+        self.commands.run("xdotool click 1")
+
+    def double_click(self, x: Optional[int] = None, y: Optional[int] = None):
+        """
+        Double left click on the mouse position.
+        """
+        if x and y:
+            self.move_mouse(x, y)
+        self.commands.run("xdotool click --repeat 2 1")
+
+    def right_click(self, x: Optional[int] = None, y: Optional[int] = None):
+        if (x is None) != (y is None):
+            raise ValueError("Both x and y must be provided together")
+        """
+        Right click on the mouse position.
+        """
+        if x and y:
+            self.move_mouse(x, y)
+        self.commands.run("xdotool click 3")
+
+    def middle_click(self, x: Optional[int] = None, y: Optional[int] = None):
+        """
+        Middle click on the mouse position.
+        """
+        if x and y:
+            self.move_mouse(x, y)
+        self.commands.run("xdotool click 2")
+
+    def scroll(self, direction: Literal["up", "down"] = "down", amount: int = 1):
+        """
+        Scroll the mouse wheel by the given amount.
+
+        :param direction: The direction to scroll. Can be "up" or "down".
+        :param amount: The amount to scroll.
+        """
+        self.commands.run(
+            f"xdotool click --repeat {amount} {'4' if direction == 'up' else '5'}"
+        )
+
+    def move_mouse(self, x: int, y: int):
+        """
+        Move the mouse to the given coordinates.
+
+        :param x: The x coordinate.
+        :param y: The y coordinate.
+        """
+        self.commands.run(f"xdotool mousemove --sync {x} {y}")
+
+    def mouse_press(self, button: Literal["left", "right", "middle"] = "left"):
+        """
+        Press the mouse button.
+        """
+        self.commands.run(f"xdotool mousedown {MOUSE_BUTTONS[button]}")
+
+    def mouse_release(self, button: Literal["left", "right", "middle"] = "left"):
+        """
+        Release the mouse button.
+        """
+        self.commands.run(f"xdotool mouseup {MOUSE_BUTTONS[button]}")
+
+    def get_cursor_position(self) -> tuple[int, int]:
+        """
+        Get the current cursor position.
+
+        :return: A tuple with the x and y coordinates
+        :raises RuntimeError: If the cursor position cannot be determined
+        """
+        result = self.commands.run("xdotool getmouselocation")
+
+        groups = re_search(r"x:(\d+)\s+y:(\d+)", result.stdout)
+        if not groups:
+            raise RuntimeError(
+                f"Failed to parse cursor position from output: {result.stdout}"
+            )
+
+        x, y = groups.group(1), groups.group(2)
+        if not x or not y:
+            raise RuntimeError(f"Invalid cursor position values: x={x}, y={y}")
+
+        return int(x), int(y)
+
+    def get_screen_size(self) -> tuple[int, int]:
+        """
+        Get the current screen size.
+
+        :return: A tuple with the width and height
+        :raises RuntimeError: If the screen size cannot be determined
+        """
+        result = self.commands.run("xrandr")
+
+        _match = re_search(r"(\d+x\d+)", result.stdout)
+        if not _match:
+            raise RuntimeError(
+                f"Failed to parse screen size from output: {result.stdout}"
+            )
+
+        try:
+            return tuple(map(int, _match.group(1).split("x")))  # type: ignore
+        except (ValueError, IndexError) as e:
+            raise RuntimeError(f"Invalid screen size format: {_match.group(1)}") from e
+
+    def write(self, text: str, *, chunk_size: int = 25, delay_in_ms: int = 75) -> None:
+        """
+        Write the given text at the current cursor position.
+
+        :param text: The text to write.
+        :param chunk_size: The size of each chunk of text to write.
+        :param delay_in_ms: The delay between each chunk of text.
+        """
+
+        def break_into_chunks(text: str, n: int):
+            for i in range(0, len(text), n):
+                yield text[i : i + n]
+
+        for chunk in break_into_chunks(text, chunk_size):
+            self.commands.run(
+                f"xdotool type --delay {delay_in_ms} -- {quote_string(chunk)}"
+            )
+
+    def press(self, key: Union[str, list[str]]):
+        """
+        Press a key.
+
+        :param key: The key to press (e.g. "enter", "space", "backspace", etc.).
+        """
+        if isinstance(key, list):
+            key = "+".join(map_key(k) for k in key)
+        else:
+            key = map_key(key)
+
+        self.commands.run(f"xdotool key {key}")
+
+    def drag(self, fr: tuple[int, int], to: tuple[int, int]):
+        """
+        Drag the mouse from the given position to the given position.
+
+        :param from: The starting position.
+        :param to: The ending position.
+        """
+        self.move_mouse(fr[0], fr[1])
+        self.mouse_press()
+        self.move_mouse(to[0], to[1])
+        self.mouse_release()
+
+    def wait(self, ms: int):
+        """
+        Wait for the given amount of time.
+
+        :param ms: The amount of time to wait in milliseconds.
+        """
+        self.commands.run(f"sleep {ms / 1000}")
+
+    def open(self, file_or_url: str):
+        """
+        Open a file or a URL in the default application.
+
+        :param file_or_url: The file or URL to open.
+        """
+        handle = self.commands.run(f"xdg-open {file_or_url}", background=True)
+        handle.disconnect()
+
+    def get_current_window_id(self) -> str:
+        """
+        Get the current window ID.
+        """
+        return self.commands.run("xdotool getwindowfocus").stdout.strip()
+
+    def get_application_windows(self, application: str) -> list[str]:
+        """
+        Get the window IDs of all windows for the given application.
+        """
+        return (
+            self.commands.run(f"xdotool search --onlyvisible --class {application}")
+            .stdout.strip()
+            .split("\n")
+        )
+
+    def get_window_title(self, window_id: str) -> str:
+        """
+        Get the title of the window with the given ID.
+        """
+        return self.commands.run(f"xdotool getwindowname {window_id}").stdout.strip()
+
+    def launch(self, application: str, uri: Optional[str] = None):
+        """
+        Launch an application.
+        """
+        handle = self.commands.run(
+            f"gtk-launch {application} {uri or ''}", background=True, timeout=0
+        )
+        handle.disconnect()

boxfab_desktop-0.1.0a1/pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "boxfab-desktop"
+version = "0.1.0a1"
+description = "BoxFab Desktop: a virtual Linux desktop in a BoxFab sandbox, for computer-use agents"
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "boxfab>=0.1.0a3,<0.2",
+    "requests>=2.32.3,<3",
+    "urllib3>=2.8.0,<3",
+    "pillow>=13.0.0,<14",
+]
+
+[[project.authors]]
+name = "ContextFab, Inc."
+
+[project.urls]
+Repository = "https://github.com/boxfab/python-sdk"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3,<10",
+    "python-dotenv>=1.0.0,<2",
+    "pytest-dotenv>=0.5.2,<0.6",
+    "pytest-xdist>=3.6.1,<4",
+]
+
+[tool.uv.sources.boxfab]
+path = ".."
+editable = true
+
+[tool.uv.build-backend]
+module-name = ["boxfab_desktop"]
+module-root = ""
+source-exclude = ["tests"]
+
+[build-system]
+requires = ["uv_build>=0.13.4,<0.14.0"]
+build-backend = "uv_build"

boxfab_desktop-0.1.0a1/pyproject.toml.orig

@@ -0,0 +1,50 @@
+[project]
+name = "boxfab-desktop"
+version = "0.1.0a1"
+description = "BoxFab Desktop: a virtual Linux desktop in a BoxFab sandbox, for computer-use agents"
+authors = [{ name = "ContextFab, Inc." }]
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+# The core SDK in this repository is generated from the same upstream commit. The other ranges
+# are upstream's (e2b-desktop 2.7.2).
+dependencies = [
+    "boxfab>=0.1.0a3,<0.2",
+    "requests>=2.32.3,<3",
+    "urllib3>=2.8.0,<3",
+    "pillow>=13.0.0,<14",
+]
+
+[project.urls]
+Repository = "https://github.com/boxfab/python-sdk"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3,<10",
+    "python-dotenv>=1.0.0,<2",
+    "pytest-dotenv>=0.5.2,<0.6",
+    "pytest-xdist>=3.6.1,<4",
+]
+
+# Development uses the core SDK from this repository; the published package depends on the
+# released `boxfab` (range above).
+[tool.uv.sources]
+boxfab = { path = "..", editable = true }
+
+[build-system]
+requires = ["uv_build>=0.13.4,<0.14.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = ["boxfab_desktop"]
+module-root = ""
+source-exclude = ["tests"]