boxlite 0.4.0.dev0__cp311-cp311-macosx_14_0_arm64.whl

boxlite/__init__.py

@@ -0,0 +1,92 @@
+"""
+BoxLite - Lightweight, secure containerization for any environment.
+
+Following SQLite philosophy: "BoxLite" for branding, "boxlite" for code APIs.
+"""
+
+import os
+import warnings
+from pathlib import Path
+
+# Import core Rust API
+try:
+    from .boxlite import (
+        Options,
+        BoxOptions,
+        Boxlite,
+        Box,
+        Execution,
+        ExecStdout,
+        ExecStderr,
+        BoxInfo,
+        RuntimeMetrics,
+        BoxMetrics,
+    )
+
+    __all__ = [
+        # Core Rust API
+        "Options",
+        "BoxOptions",
+        "Boxlite",
+        "Box",
+        "Execution",
+        "ExecStdout",
+        "ExecStderr",
+        "BoxInfo",
+        "RuntimeMetrics",
+        "BoxMetrics",
+    ]
+except ImportError as e:
+    warnings.warn(f"BoxLite native extension not available: {e}", ImportWarning)
+    __all__ = []
+
+# Import Python convenience wrappers
+try:
+    from .simplebox import SimpleBox
+    from .exec import ExecResult
+    from .codebox import CodeBox
+    from .errors import BoxliteError, ExecError, TimeoutError, ParseError
+
+    __all__.extend([
+        # Python convenience wrappers
+        "SimpleBox",
+        "CodeBox",
+        "ExecResult",
+        # Error types
+        "BoxliteError",
+        "ExecError",
+        "TimeoutError",
+        "ParseError",
+    ])
+except ImportError:
+    pass
+
+# Specialized containers
+try:
+    from .browserbox import BrowserBox, BrowserBoxOptions
+
+    __all__.extend(["BrowserBox", "BrowserBoxOptions"])
+except ImportError:
+    pass
+
+try:
+    from .computerbox import ComputerBox
+
+    __all__.extend(["ComputerBox"])
+except ImportError:
+    pass
+
+try:
+    from .interactivebox import InteractiveBox
+
+    __all__.extend(["InteractiveBox"])
+except ImportError:
+    pass
+
+# Get version from package metadata
+try:
+    from importlib.metadata import version, PackageNotFoundError
+    __version__ = version("boxlite")
+except PackageNotFoundError:
+    # Package not installed (e.g., development mode)
+    __version__ = "0.0.0+dev"

boxlite/browserbox.py

@@ -0,0 +1,138 @@
+"""
+BrowserBox - Secure browser with remote debugging.
+
+Provides a minimal, elegant API for running isolated browsers that can be
+controlled from outside using standard tools like Puppeteer or Playwright.
+"""
+
+from dataclasses import dataclass
+from typing import Optional, TYPE_CHECKING
+
+from .simplebox import SimpleBox, StreamType
+
+if TYPE_CHECKING:
+    from .boxlite import Boxlite
+
+__all__ = ["BrowserBox", "BrowserBoxOptions"]
+
+
+@dataclass
+class BrowserBoxOptions:
+    """
+    Configuration for BrowserBox.
+
+    Example:
+        >>> opts = BrowserBoxOptions(
+        ...     browser="chromium",
+        ...     memory=2048,
+        ...     cpu=2
+        ... )
+        >>> async with BrowserBox(opts) as browser:
+        ...     print(browser.endpoint())
+    """
+    browser: str = "chromium"  # chromium, firefox, or webkit
+    memory: int = 2048  # Memory in MiB
+    cpu: int = 2  # Number of CPU cores
+
+
+class BrowserBox(SimpleBox):
+    """
+    Secure browser environment with remote debugging.
+
+    Auto-starts a browser with Chrome DevTools Protocol enabled.
+    Connect from outside using Puppeteer, Playwright, Selenium, or DevTools.
+
+    Usage:
+        >>> async with BrowserBox() as browser:
+        ...     print(f"Connect to: {browser.endpoint()}")
+        ...     # Use Puppeteer/Playwright from your host to connect
+        ...     await asyncio.sleep(60)
+
+    Example with custom options:
+        >>> opts = BrowserBoxOptions(browser="firefox", memory=4096)
+        >>> async with BrowserBox(opts) as browser:
+        ...     endpoint = browser.endpoint()
+    """
+
+    # Default Playwright images (with retry logic now!)
+    _DEFAULT_IMAGE = "mcr.microsoft.com/playwright:v1.47.2-jammy"
+
+    # CDP port for each browser type
+    _PORTS = {"chromium": 9222, "firefox": 9223, "webkit": 9224}
+
+    def __init__(self, options: Optional[BrowserBoxOptions] = None,
+                 runtime: Optional['Boxlite'] = None,
+                 **kwargs):
+        """
+        Create and auto-start a browser.
+
+        Args:
+            options: Browser configuration (uses defaults if None)
+            runtime: Optional runtime instance (uses global default if None)
+            **kwargs: Additional configuration options (volumes, env, etc.)
+        """
+        opts = options or BrowserBoxOptions()
+
+        self._browser = opts.browser
+        self._port = self._PORTS.get(opts.browser, 9222)
+
+        # Initialize base box
+        super().__init__(
+            image=self._DEFAULT_IMAGE,
+            memory_mib=opts.memory,
+            cpus=opts.cpu,
+            runtime=runtime,
+            **kwargs
+        )
+
+    async def __aenter__(self):
+        """Start browser automatically on context enter."""
+        await super().__aenter__()
+        await self._start_browser()
+        return self
+
+    async def _start_browser(self):
+        """Internal: Start browser with remote debugging."""
+        if self._browser == "chromium":
+            binary = "/ms-playwright/chromium-*/chrome-linux/chrome"
+            cmd = (
+                f"{binary} --headless --no-sandbox --disable-dev-shm-usage "
+                f"--disable-gpu --remote-debugging-address=0.0.0.0 "
+                f"--remote-debugging-port={self._port} "
+                f"> /tmp/browser.log 2>&1 &"
+            )
+        elif self._browser == "firefox":
+            binary = "/ms-playwright/firefox-*/firefox/firefox"
+            cmd = (
+                f"{binary} --headless "
+                f"--remote-debugging-port={self._port} "
+                f"> /tmp/browser.log 2>&1 &"
+            )
+        else:  # webkit
+            cmd = (
+                f"playwright run-server --browser webkit "
+                f"--port {self._port} > /tmp/browser.log 2>&1 &"
+            )
+
+        # Start browser in background
+        await self.exec("sh", "-c", f"nohup {cmd}")
+
+        # Wait for browser to be ready
+        await self.exec("sleep", "3")
+
+    def endpoint(self) -> str:
+        """
+        Get the connection endpoint for remote debugging.
+
+        Returns:
+            HTTP endpoint URL for Chrome DevTools Protocol
+
+        Example:
+            >>> async with BrowserBox() as browser:
+            ...     url = browser.endpoint()
+            ...     # Use with Puppeteer:
+            ...     # puppeteer.connect({ browserURL: url })
+            ...     # Use with Playwright:
+            ...     # chromium.connect_over_cdp(url)
+        """
+        return f"http://localhost:{self._port}"

boxlite/codebox.py

@@ -0,0 +1,120 @@
+"""
+CodeBox - Secure Python code execution container.
+
+Provides a simple, secure environment for running untrusted Python code.
+"""
+
+from typing import Optional, TYPE_CHECKING
+
+from .simplebox import SimpleBox
+
+if TYPE_CHECKING:
+    from .boxlite import Boxlite
+
+
+class CodeBox(SimpleBox):
+    """
+    Secure container for executing Python code.
+
+    CodeBox provides an isolated environment for running untrusted Python code
+    with built-in safety and result formatting.
+
+    Usage:
+        >>> async with CodeBox() as cb:
+        ...     result = await cb.run("print('Hello, World!')")
+    """
+
+    def __init__(
+            self,
+            image: str = "python:slim",
+            memory_mib: Optional[int] = None,
+            cpus: Optional[int] = None,
+            runtime: Optional['Boxlite'] = None,
+            **kwargs
+    ):
+        """
+        Create a new CodeBox.
+
+        Args:
+            image: Container images with Python (default: python:slim)
+            memory_mib: Memory limit in MiB (default: system default)
+            cpus: Number of CPU cores (default: system default)
+            runtime: Optional runtime instance (uses global default if None)
+            **kwargs: Additional configuration options
+        """
+        super().__init__(image, memory_mib, cpus, runtime, **kwargs)
+
+    async def run(self, code: str, timeout: Optional[int] = None) -> str:
+        """
+        Execute Python code in the secure container.
+
+        Args:
+            code: Python code to execute
+            timeout: Execution timeout in seconds (not yet implemented)
+
+        Returns:
+            Execution output as a string (stdout + stderr)
+
+        Example:
+            >>> async with CodeBox() as cb:
+            ...     result = await cb.run("print('Hello, World!')")
+            ...     print(result)
+            Hello, World!
+
+        Note:
+            Uses python3 from the container images.
+            For custom Python paths, use exec() directly:
+                result = await cb.exec("/path/to/python", "-c", code)
+        """
+        # Execute Python code using python3 -c
+        result = await self.exec("/usr/local/bin/python", "-c", code)
+        return result.stdout + result.stderr
+
+    async def run_script(self, script_path: str) -> str:
+        """
+        Execute a Python script file in the container.
+
+        Args:
+            script_path: Path to the Python script on the host
+
+        Returns:
+            Execution output as a string
+        """
+        with open(script_path, 'r') as f:
+            code = f.read()
+        return await self.run(code)
+
+    async def install_package(self, package: str) -> str:
+        """
+        Install a Python package in the container using pip.
+
+        Args:
+            package: Package name (e.g., 'requests', 'numpy==1.24.0')
+
+        Returns:
+            Installation output
+
+        Example:
+            >>> async with CodeBox() as cb:
+            ...     await cb.install_package("requests")
+            ...     result = await cb.run("import requests; print(requests.__version__)")
+        """
+        result = await self.exec("pip", "install", package)
+        return result.stdout + result.stderr
+
+    async def install_packages(self, *packages: str) -> str:
+        """
+        Install multiple Python packages.
+
+        Args:
+            *packages: Package names to install
+
+        Returns:
+            Installation output
+
+        Example:
+            >>> async with CodeBox() as cb:
+            ...     await cb.install_packages("requests", "numpy", "pandas")
+        """
+        result = await self.exec("pip", "install", *packages)
+        return result.stdout + result.stderr

boxlite/computerbox.py

@@ -0,0 +1,267 @@
+"""
+ComputerBox - Desktop environment with web access.
+
+Provides a minimal, elegant API for running isolated desktop environments
+that can be viewed from a browser, with full GUI automation support.
+"""
+
+import asyncio
+import logging
+from typing import Optional, Tuple, TYPE_CHECKING
+
+from . import constants as const
+from .errors import ExecError, TimeoutError, ParseError
+from .simplebox import SimpleBox
+
+if TYPE_CHECKING:
+    from .boxlite import Boxlite
+
+__all__ = ["ComputerBox"]
+
+logger = logging.getLogger("boxlite.computerbox")
+
+
+class ComputerBox(SimpleBox):
+    """
+    Desktop environment accessible via web browser.
+
+    Auto-starts a full desktop environment with web interface.
+    Access the desktop by opening the URL in your browser.
+
+    Note: Uses HTTPS with self-signed certificate - your browser will show
+    a security warning. Click "Advanced" and "Proceed" to access the desktop.
+
+    Usage:
+        >>> async with ComputerBox() as desktop:
+        ...     await desktop.wait_until_ready()
+        ...     screenshot = await desktop.screenshot()
+
+    Example with custom settings:
+        >>> async with ComputerBox(memory=4096, cpu=4) as desktop:
+        ...     await desktop.mouse_move(100, 200)
+        ...     await desktop.left_click()
+    """
+
+    def __init__(
+        self,
+        cpu: int = const.COMPUTERBOX_CPUS,
+        memory: int = const.COMPUTERBOX_MEMORY_MIB,
+        gui_http_port: int = const.COMPUTERBOX_GUI_HTTP_PORT,
+        gui_https_port: int = const.COMPUTERBOX_GUI_HTTPS_PORT,
+        runtime: Optional['Boxlite'] = None,
+        **kwargs
+    ):
+        """
+        Create and auto-start a desktop environment.
+
+        Args:
+            cpu: Number of CPU cores (default: 2)
+            memory: Memory in MiB (default: 2048)
+            gui_http_port: Port for HTTP desktop GUI (default: 3000)
+            gui_https_port: Port for HTTPS desktop GUI (default: 3001)
+            runtime: Optional runtime instance (uses global default if None)
+            **kwargs: Additional configuration options (volumes, etc.)
+        """
+        user_env = kwargs.pop('env', [])
+        default_env = [
+            ("DISPLAY", const.COMPUTERBOX_DISPLAY_NUMBER),
+            ("DISPLAY_SIZEW", str(const.COMPUTERBOX_DISPLAY_WIDTH)),
+            ("DISPLAY_SIZEH", str(const.COMPUTERBOX_DISPLAY_HEIGHT)),
+            ("SELKIES_MANUAL_WIDTH", str(const.COMPUTERBOX_DISPLAY_WIDTH)),
+            ("SELKIES_MANUAL_HEIGHT", str(const.COMPUTERBOX_DISPLAY_HEIGHT)),
+            ("SELKIES_UI_SHOW_SIDEBAR", "false"),
+        ]
+
+        user_ports = kwargs.pop('ports', [])
+        default_ports = [
+            (gui_http_port, const.COMPUTERBOX_GUI_HTTP_PORT),
+            (gui_https_port, const.COMPUTERBOX_GUI_HTTPS_PORT)
+        ]
+
+        super().__init__(
+            image=const.COMPUTERBOX_IMAGE,
+            memory_mib=memory,
+            cpus=cpu,
+            runtime=runtime,
+            env=default_env + list(user_env),
+            ports=default_ports + list(user_ports),
+            **kwargs
+        )
+
+    async def wait_until_ready(self, timeout: int = const.DESKTOP_READY_TIMEOUT):
+        """
+        Wait until the desktop environment is fully loaded and ready.
+
+        Args:
+            timeout: Maximum time to wait in seconds (default: 60)
+
+        Raises:
+            TimeoutError: If desktop doesn't become ready within timeout period
+        """
+        logger.info("Waiting for desktop to become ready...")
+        import time
+        start_time = time.time()
+
+        while True:
+            elapsed = time.time() - start_time
+            if elapsed > timeout:
+                raise TimeoutError(f"Desktop did not become ready within {timeout} seconds")
+
+            try:
+                exec_result = await self.exec("xwininfo", "-tree", "-root")
+                expected_size = f'{const.COMPUTERBOX_DISPLAY_WIDTH}x{const.COMPUTERBOX_DISPLAY_HEIGHT}'
+
+                if 'xfdesktop' in exec_result.stdout and expected_size in exec_result.stdout:
+                    logger.info(f"Desktop ready after {elapsed:.1f} seconds")
+                    return
+
+                logger.debug(f"Desktop not ready yet (waited {elapsed:.1f}s), retrying...")
+                await asyncio.sleep(const.DESKTOP_READY_RETRY_DELAY)
+
+            except (ExecError, ConnectionError, OSError, asyncio.TimeoutError) as e:
+                logger.debug(f"Desktop not ready: {e}, retrying...")
+                await asyncio.sleep(const.DESKTOP_READY_RETRY_DELAY)
+            except Exception as e:
+                logger.error(f"Fatal error in wait_until_ready: {e}")
+                raise
+
+    async def screenshot(self) -> dict:
+        """
+        Capture a screenshot of the desktop.
+
+        Returns:
+            Dictionary with: data (base64 PNG), width, height, format
+        """
+        logger.info("Taking screenshot...")
+
+        python_code = '''
+from PIL import ImageGrab
+import io
+import base64
+img = ImageGrab.grab()
+buffer = io.BytesIO()
+img.save(buffer, format="PNG")
+print(base64.b64encode(buffer.getvalue()).decode("utf-8"))
+'''
+        exec_result = await self.exec("python3", "-c", python_code)
+
+        if exec_result.exit_code != 0:
+            raise ExecError("screenshot()", exec_result.exit_code, exec_result.stderr)
+
+        return {
+            "data": exec_result.stdout.strip(),
+            "width": const.COMPUTERBOX_DISPLAY_WIDTH,
+            "height": const.COMPUTERBOX_DISPLAY_HEIGHT,
+            "format": "png"
+        }
+
+    async def mouse_move(self, x: int, y: int):
+        """Move mouse cursor to absolute coordinates."""
+        exec_result = await self.exec("xdotool", "mousemove", str(x), str(y))
+        if exec_result.exit_code != 0:
+            raise ExecError(f"mouse_move({x}, {y})", exec_result.exit_code, exec_result.stderr)
+
+    async def left_click(self):
+        """Click left mouse button at current position."""
+        exec_result = await self.exec("xdotool", "click", "1")
+        if exec_result.exit_code != 0:
+            raise ExecError("left_click()", exec_result.exit_code, exec_result.stderr)
+
+    async def right_click(self):
+        """Click right mouse button at current position."""
+        exec_result = await self.exec("xdotool", "click", "3")
+        if exec_result.exit_code != 0:
+            raise ExecError("right_click()", exec_result.exit_code, exec_result.stderr)
+
+    async def middle_click(self):
+        """Click middle mouse button at current position."""
+        exec_result = await self.exec("xdotool", "click", "2")
+        if exec_result.exit_code != 0:
+            raise ExecError("middle_click()", exec_result.exit_code, exec_result.stderr)
+
+    async def double_click(self):
+        """Double-click left mouse button at current position."""
+        exec_result = await self.exec("xdotool", "click", "--repeat", "2", "--delay", "100", "1")
+        if exec_result.exit_code != 0:
+            raise ExecError("double_click()", exec_result.exit_code, exec_result.stderr)
+
+    async def triple_click(self):
+        """Triple-click left mouse button at current position."""
+        exec_result = await self.exec("xdotool", "click", "--repeat", "3", "--delay", "100", "1")
+        if exec_result.exit_code != 0:
+            raise ExecError("triple_click()", exec_result.exit_code, exec_result.stderr)
+
+    async def left_click_drag(self, start_x: int, start_y: int, end_x: int, end_y: int):
+        """Drag mouse from start position to end position with left button held."""
+        exec_result = await self.exec(
+            "xdotool",
+            "mousemove", str(start_x), str(start_y),
+            "mousedown", "1",
+            "sleep", "0.1",
+            "mousemove", str(end_x), str(end_y),
+            "sleep", "0.1",
+            "mouseup", "1"
+        )
+        if exec_result.exit_code != 0:
+            raise ExecError("left_click_drag()", exec_result.exit_code, exec_result.stderr)
+
+    async def cursor_position(self) -> Tuple[int, int]:
+        """Get the current mouse cursor position. Returns (x, y) tuple."""
+        exec_result = await self.exec("xdotool", "getmouselocation", "--shell")
+        if exec_result.exit_code != 0:
+            raise ExecError("cursor_position()", exec_result.exit_code, exec_result.stderr)
+
+        x, y = None, None
+        for line in exec_result.stdout.split('\n'):
+            line = line.strip()
+            if line.startswith('X='):
+                x = int(line[2:])
+            elif line.startswith('Y='):
+                y = int(line[2:])
+
+        if x is not None and y is not None:
+            return (x, y)
+        raise ParseError("Failed to parse cursor position from xdotool output")
+
+    async def type(self, text: str):
+        """Type text using the keyboard."""
+        exec_result = await self.exec("xdotool", "type", "--", text)
+        if exec_result.exit_code != 0:
+            raise ExecError("type()", exec_result.exit_code, exec_result.stderr)
+
+    async def key(self, text: str):
+        """Press a special key or key combination (e.g., 'Return', 'ctrl+c')."""
+        exec_result = await self.exec("xdotool", "key", text)
+        if exec_result.exit_code != 0:
+            raise ExecError("key()", exec_result.exit_code, exec_result.stderr)
+
+    async def scroll(self, x: int, y: int, direction: str, amount: int = 3):
+        """
+        Scroll at a specific position.
+
+        Args:
+            x, y: Coordinates where to scroll
+            direction: 'up', 'down', 'left', or 'right'
+            amount: Number of scroll units (default: 3)
+        """
+        direction_map = {"up": "4", "down": "5", "left": "6", "right": "7"}
+        button = direction_map.get(direction.lower())
+        if not button:
+            raise ValueError(f"Invalid scroll direction: {direction}")
+
+        exec_result = await self.exec(
+            "xdotool", "mousemove", str(x), str(y), "click", "--repeat", str(amount), button
+        )
+        if exec_result.exit_code != 0:
+            raise ExecError("scroll()", exec_result.exit_code, exec_result.stderr)
+
+    async def get_screen_size(self) -> Tuple[int, int]:
+        """Get the screen resolution. Returns (width, height) tuple."""
+        exec_result = await self.exec("xdotool", "getdisplaygeometry")
+        if exec_result.exit_code != 0:
+            raise ExecError("get_screen_size()", exec_result.exit_code, exec_result.stderr)
+
+        parts = exec_result.stdout.strip().split()
+        if len(parts) == 2:
+            return (int(parts[0]), int(parts[1]))
+        raise ParseError("Failed to parse screen size from xdotool output")

boxlite/constants.py

@@ -0,0 +1,25 @@
+"""
+Centralized constants for BoxLite Python SDK.
+"""
+
+# Default VM resources
+DEFAULT_CPUS = 1
+DEFAULT_MEMORY_MIB = 2048
+
+# ComputerBox defaults (higher resources for desktop)
+COMPUTERBOX_CPUS = 2
+COMPUTERBOX_MEMORY_MIB = 2048
+COMPUTERBOX_IMAGE = "lscr.io/linuxserver/webtop:ubuntu-xfce"
+
+# ComputerBox display settings
+COMPUTERBOX_DISPLAY_NUMBER = ":1"
+COMPUTERBOX_DISPLAY_WIDTH = 1024
+COMPUTERBOX_DISPLAY_HEIGHT = 768
+
+# ComputerBox network ports (webtop defaults)
+COMPUTERBOX_GUI_HTTP_PORT = 3000
+COMPUTERBOX_GUI_HTTPS_PORT = 3001
+
+# Timeouts (seconds)
+DESKTOP_READY_TIMEOUT = 60
+DESKTOP_READY_RETRY_DELAY = 0.5

boxlite/errors.py

@@ -0,0 +1,38 @@
+"""
+BoxLite error types.
+
+Provides a hierarchy of exceptions for different failure modes.
+"""
+
+__all__ = ['BoxliteError', 'ExecError', 'TimeoutError', 'ParseError']
+
+
+class BoxliteError(Exception):
+    """Base exception for all boxlite errors."""
+    pass
+
+
+class ExecError(BoxliteError):
+    """
+    Raised when a command execution fails (non-zero exit code).
+
+    Attributes:
+        command: The command that failed
+        exit_code: The non-zero exit code
+        stderr: Standard error output from the command
+    """
+    def __init__(self, command: str, exit_code: int, stderr: str):
+        self.command = command
+        self.exit_code = exit_code
+        self.stderr = stderr
+        super().__init__(f"Command '{command}' failed with exit code {exit_code}: {stderr}")
+
+
+class TimeoutError(BoxliteError):
+    """Raised when an operation times out."""
+    pass
+
+
+class ParseError(BoxliteError):
+    """Raised when output parsing fails."""
+    pass

boxlite/exec.py

@@ -0,0 +1,26 @@
+"""
+Execution API - Simple interface for command execution.
+
+Provides Docker-like API for executing commands in boxes.
+"""
+
+from dataclasses import dataclass
+
+__all__ = [
+    'ExecResult',
+]
+
+
+@dataclass
+class ExecResult:
+    """
+    Result from a command execution.
+
+    Attributes:
+        exit_code: Exit code from the command (negative if terminated by signal)
+        stdout: Standard output as string
+        stderr: Standard error as string
+    """
+    exit_code: int
+    stdout: str
+    stderr: str

boxlite/interactivebox.py

@@ -0,0 +1,297 @@
+"""
+InteractiveBox - Interactive terminal sessions with PTY support.
+
+Provides automatic PTY-based interactive sessions, similar to `docker exec -it`.
+"""
+
+import asyncio
+import logging
+import os
+import sys
+import termios
+import tty
+from typing import Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .runtime import Boxlite
+
+# Configure logger
+logger = logging.getLogger("boxlite.interactivebox")
+
+
+class InteractiveBox:
+    """
+    Interactive box with automatic PTY and terminal forwarding.
+
+    When used as a context manager, automatically:
+    1. Auto-detects terminal size (like Docker)
+    2. Starts a shell with PTY
+    3. Sets local terminal to cbreak mode
+    4. Forwards stdin/stdout bidirectionally
+    5. Restores terminal mode on exit
+
+    Example:
+        async with InteractiveBox(image="alpine:latest") as box:
+            # You're now in an interactive shell!
+            # Type commands, see output in real-time
+            # Type "exit" to close
+            pass
+    """
+
+    def __init__(
+            self,
+            image: str,
+            shell: str = "/bin/sh",
+            tty: Optional[bool] = None,
+            memory_mib: Optional[int] = None,
+            cpus: Optional[int] = None,
+            runtime: Optional['Boxlite'] = None,
+            name: Optional[str] = None,
+            auto_remove: bool = True,
+            **kwargs
+    ):
+        """
+        Create interactive box.
+
+        Args:
+            image: Container image to use
+            shell: Shell to run (default: /bin/sh)
+            tty: Control terminal I/O forwarding behavior:
+                - None (default): Auto-detect - forward I/O if stdin is a TTY
+                - True: Force I/O forwarding (manual interactive mode)
+                - False: No I/O forwarding (programmatic control only)
+            memory_mib: Memory limit in MiB
+            cpus: Number of CPU cores
+            runtime: Optional runtime instance (uses global default if None)
+            name: Optional name for the box (must be unique)
+            auto_remove: Remove box when stopped (default: True)
+            **kwargs: Additional configuration options (working_dir, env)
+        """
+        try:
+            from .boxlite import Boxlite, BoxOptions
+        except ImportError as e:
+            raise ImportError(
+                f"BoxLite native extension not found: {e}. "
+                "Please install with: pip install boxlite"
+            )
+
+        # Use provided runtime or get default
+        if runtime is None:
+            self._runtime = Boxlite.default()
+        else:
+            self._runtime = runtime
+
+        # Create box options
+        box_opts = BoxOptions(
+            image=image,
+            cpus=cpus,
+            memory_mib=memory_mib,
+            auto_remove=auto_remove,
+            **kwargs
+        )
+
+        # Create box directly (no SimpleBox wrapper)
+        self._box = self._runtime.create(box_opts, name=name)
+
+        # Store interactive config
+        self._shell = shell
+        self._env = kwargs.get('env', [])
+
+        # Determine TTY mode: None = auto-detect, True = force, False = disable
+        if tty is None:
+            self._tty = sys.stdin.isatty()
+        else:
+            self._tty = tty
+
+        # Interactive state
+        self._old_tty_settings = None
+        self._io_task = None
+        self._execution = None
+        self._stdin = None
+        self._stdout = None
+        self._stderr = None
+        self._exited = None  # Event to signal process exit
+
+    @property
+    def id(self) -> str:
+        """Get the box ID."""
+        return self._box.id
+
+    async def __aenter__(self):
+        """Start box and enter interactive TTY session."""
+        # Start box directly
+        await self._box.__aenter__()
+
+        # Start shell with PTY
+        self._execution = await self._start_interactive_shell()
+
+        # Get stdin/stdout/stderr ONCE (can only be called once due to .take())
+        self._stdin = self._execution.stdin()
+        self._stdout = self._execution.stdout()
+        self._stderr = self._execution.stderr()
+
+        # Only set cbreak mode and start forwarding if tty=True
+        if self._tty:
+            stdin_fd = sys.stdin.fileno()
+            self._old_tty_settings = termios.tcgetattr(stdin_fd)
+            tty.setraw(sys.stdin.fileno(), when=termios.TCSANOW)
+
+            # Create exit event for graceful shutdown
+            self._exited = asyncio.Event()
+
+            # Start bidirectional I/O forwarding using gather (more Pythonic)
+            self._io_task = asyncio.gather(
+                self._forward_stdin(),
+                self._forward_output(),
+                self._forward_stderr(),
+                self._wait_for_exit(),
+                return_exceptions=True
+            )
+        else:
+            # No I/O forwarding, just wait for execution
+            self._io_task = self._wait_for_exit()
+
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        # Restore terminal settings
+        if self._old_tty_settings is not None:
+            try:
+                termios.tcsetattr(sys.stdin.fileno(), termios.TCSADRAIN, self._old_tty_settings)
+            except Exception as e:
+                logger.error(f"Caught exception on TTY settings: {e}")
+
+        """Exit interactive session and restore terminal."""
+        # Wait for I/O task to complete (or cancel if needed)
+        if hasattr(self, '_io_task') and self._io_task is not None:
+            try:
+                # Give it a moment to finish naturally
+                await asyncio.wait_for(self._io_task, timeout=3)
+                logger.info("Closing interactive shell (I/O tasks finished).")
+                self._io_task = None
+            except asyncio.TimeoutError:
+                # If it doesn't finish, that's ok - box is shutting down anyway
+                logger.error("Timeout waiting for I/O tasks to finish, cancelling...")
+            except Exception as e:
+                # Ignore other exceptions during cleanup
+                logger.error(f"Caught exception on exit: {e}")
+
+        # Shutdown box directly
+        return await self._box.__aexit__(exc_type, exc_val, exc_tb)
+
+    async def wait(self):
+        await self._execution.wait()
+
+    async def _start_interactive_shell(self):
+        """Start shell with PTY (internal)."""
+        # Execute shell with PTY using simplified boolean API
+        # Terminal size is auto-detected (like Docker)
+        execution = await self._box.exec(
+            self._shell,
+            args=[],
+            env=self._env,
+            tty=True,  # Simple boolean - auto-detects terminal size
+        )
+
+        return execution
+
+    async def _forward_stdin(self):
+        """Forward stdin to PTY (internal)."""
+        try:
+            if self._stdin is None:
+                return
+
+            # Forward stdin in chunks
+            loop = asyncio.get_event_loop()
+            while not self._exited.is_set():
+                # Read from stdin with timeout to check exit event
+                try:
+                    read_task = loop.run_in_executor(None, os.read, sys.stdin.fileno(), 1024)
+                    # Wait for either stdin data or exit event
+                    done, pending = await asyncio.wait(
+                        [asyncio.ensure_future(read_task),
+                         asyncio.ensure_future(self._exited.wait())],
+                        return_when=asyncio.FIRST_COMPLETED
+                    )
+
+                    # Cancel pending tasks
+                    for task in pending:
+                        task.cancel()
+
+                    # Check if we exited
+                    if self._exited.is_set():
+                        logger.info("Closing interactive shell (stdin forwarding).")
+                        break
+
+                    # Get the data from completed read task
+                    for task in done:
+                        if task.exception() is None:
+                            data = task.result()
+                            if isinstance(data, bytes) and data:
+                                await self._stdin.send_input(data)
+                            elif not data:
+                                # EOF
+                                return
+
+                except asyncio.CancelledError:
+                    break
+
+        except asyncio.CancelledError:
+            logger.info("Cancelling interactive shell (stdin forwarding).")
+        except Exception as e:
+            logger.error(f"Caught exception on stdin: {e}")
+
+    async def _forward_output(self):
+        """Forward PTY output to stdout (internal)."""
+        try:
+            if self._stdout is None:
+                return
+
+            # Forward all output to stdout
+            async for chunk in self._stdout:
+                # Write directly to stdout (bypass print buffering)
+                if isinstance(chunk, bytes):
+                    sys.stdout.buffer.write(chunk)
+                else:
+                    sys.stdout.buffer.write(chunk.encode('utf-8', errors='replace'))
+                sys.stdout.buffer.flush()
+
+            logger.info("\nOutput forwarding ended.")
+
+        except asyncio.CancelledError:
+            logger.error("Cancelling interactive shell (stdout forwarding).")
+        except Exception as e:
+            logger.error(f"\nError forwarding output: {e}", file=sys.stderr)
+
+    async def _forward_stderr(self):
+        """Forward PTY stderr to stderr (internal)."""
+        try:
+            if self._stderr is None:
+                return
+
+            # Forward all error output to stderr
+            async for chunk in self._stderr:
+                # Write directly to stderr (bypass print buffering)
+                if isinstance(chunk, bytes):
+                    sys.stderr.buffer.write(chunk)
+                else:
+                    sys.stderr.buffer.write(chunk.encode('utf-8', errors='replace'))
+                sys.stderr.buffer.flush()
+
+            logger.info("\nStderr forwarding ended.")
+
+        except asyncio.CancelledError:
+            logger.error("Cancelling interactive shell (stderr forwarding).")
+        except Exception as e:
+            logger.error(f"\nError forwarding stderr: {e}", file=sys.stderr)
+
+    async def _wait_for_exit(self):
+        """Wait for the shell to exit (internal)."""
+        try:
+            await self._execution.wait()
+        except Exception:
+            pass  # Ignore errors, cleanup will happen in __aexit__
+        finally:
+            # Signal other tasks to stop
+            if self._exited:
+                self._exited.set()

boxlite/simplebox.py

@@ -0,0 +1,213 @@
+"""
+SimpleBox - Foundation for specialized container types.
+
+Provides common functionality for all specialized boxes (CodeBox, BrowserBox, etc.)
+"""
+
+import logging
+from enum import IntEnum
+from typing import Optional
+
+from .exec import ExecResult
+
+logger = logging.getLogger("boxlite.simplebox")
+
+__all__ = ['SimpleBox']
+
+
+class StreamType(IntEnum):
+    """Stream type for command execution output."""
+    STDOUT = 1
+    STDERR = 2
+
+
+class SimpleBox:
+    """
+    Base class for specialized container types.
+
+    This class encapsulates the common patterns:
+    1. Async context manager support
+    2. Automatic runtime lifecycle management
+    3. Stdio blocking mode restoration
+
+    Subclasses should override:
+    - _create_box_options(): Return BoxOptions for their specific use case
+    - Add domain-specific methods (e.g., CodeBox.run(), BrowserBox.navigate())
+    """
+
+    def __init__(
+            self,
+            image: str,
+            memory_mib: Optional[int] = None,
+            cpus: Optional[int] = None,
+            runtime: Optional['Boxlite'] = None,
+            name: Optional[str] = None,
+            auto_remove: bool = True,
+            **kwargs
+    ):
+        """
+        Create a specialized box.
+
+        Args:
+            image: Container images to use
+            memory_mib: Memory limit in MiB
+            cpus: Number of CPU cores
+            runtime: Optional runtime instance (uses global default if None)
+            name: Optional name for the box (must be unique)
+            auto_remove: Remove box when stopped (default: True)
+            **kwargs: Additional configuration options
+        """
+        try:
+            from .boxlite import Boxlite
+        except ImportError as e:
+            raise ImportError(
+                f"BoxLite native extension not found: {e}. "
+                "Please install with: pip install boxlite"
+            )
+
+        # Use provided runtime or get Rust's global default
+        if runtime is None:
+            self._runtime = Boxlite.default()
+        else:
+            self._runtime = runtime
+
+        # Create box using subclass-defined options
+        try:
+            from .boxlite import BoxOptions
+        except ImportError as e:
+            raise ImportError(
+                f"BoxLite native extension not found: {e}. "
+                "Please install with: pip install boxlite"
+            )
+
+        box_opts = BoxOptions(
+            image=image,
+            cpus=cpus,
+            memory_mib=memory_mib,
+            auto_remove=auto_remove,
+            **kwargs
+        )
+        self._name = name
+        self._box = self._runtime.create(box_opts, name=name)
+
+    async def __aenter__(self):
+        """Async context manager entry - delegates to Box.__aenter__."""
+        await self._box.__aenter__()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit - delegates to Box.__aexit__ (returns awaitable)."""
+        return await self._box.__aexit__(exc_type, exc_val, exc_tb)
+
+    @property
+    def id(self) -> str:
+        """Get the box ID."""
+        return self._box.id
+
+    def info(self):
+        """Get box information."""
+        return self._box.info()
+
+    async def exec(
+            self,
+            cmd: str,
+            *args: str,
+            env: Optional[dict[str, str]] = None,
+    ) -> ExecResult:
+        """
+        Execute a command in the box and return the result.
+
+        Args:
+            cmd: Command to execute (e.g., 'ls', 'python')
+            *args: Arguments to the command (e.g., '-l', '-a')
+            env: Environment variables (default: guest's default environment)
+
+        Returns:
+            ExecResult with exit_code and output
+
+        Examples:
+            Simple execution::
+
+                result = await box.exec('ls', '-l', '-a')
+                print(f"Exit code: {result.exit_code}")
+                print(f"Stdout: {result.stdout}")
+                print(f"Stderr: {result.stderr}")
+
+            With environment variables::
+
+                result = await box.exec('env', env={'FOO': 'bar'})
+                print(result.stdout)
+        """
+
+        arg_list = list(args) if args else None
+        # Convert env dict to list of tuples if provided
+        env_list = list(env.items()) if env else None
+
+        # Execute via Rust (returns PyExecution)
+        execution = await self._box.exec(cmd, arg_list, env_list)
+
+        # Get streams from Rust execution
+        try:
+            stdout = execution.stdout()
+        except Exception as e:
+            logger.error(f"take stdout err: {e}")
+            stdout = None
+
+        try:
+            stderr = execution.stderr()
+        except Exception as e:
+            logger.error(f"take stderr err: {e}")
+            stderr = None
+
+        # Collect stdout and stderr separately
+        stdout_lines = []
+        stderr_lines = []
+
+        # Read stdout
+        if stdout:
+            logger.debug("collecting stdout")
+            try:
+                async for line in stdout:
+                    if isinstance(line, bytes):
+                        stdout_lines.append(line.decode('utf-8', errors='replace'))
+                    else:
+                        stdout_lines.append(line)
+            except Exception as e:
+                logger.error(f"collecting stdout err: {e}")
+                pass
+
+        # Read stderr
+        if stderr:
+            logger.debug("collecting stderr")
+            try:
+                async for line in stderr:
+                    if isinstance(line, bytes):
+                        stderr_lines.append(line.decode('utf-8', errors='replace'))
+                    else:
+                        stderr_lines.append(line)
+            except Exception as e:
+                logger.error(f"collecting stderr err: {e}")
+                pass
+
+        # Combine lines
+        stdout = ''.join(stdout_lines)
+        stderr = ''.join(stderr_lines)
+
+        try:
+            exec_result = await execution.wait()
+            exit_code = exec_result.exit_code
+        except Exception as e:
+            logger.error(f"failed to wait execution: {e}")
+            exit_code = -1
+
+        logger.debug(f"exec finish, exit_code: {exit_code}")
+
+        return ExecResult(exit_code=exit_code, stdout=stdout, stderr=stderr)
+
+    def shutdown(self):
+        """
+        Shutdown the box and release resources.
+
+        Note: Usually not needed as context manager handles cleanup.
+        """
+        self._box.shutdown()

boxlite-0.4.0.dev0.dist-info/METADATA

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: boxlite
+Version: 0.4.0.dev0
+Requires-Dist: pytest>=7.0 ; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21 ; extra == 'dev'
+Provides-Extra: dev
+Summary: Python bindings for Boxlite runtime
+Author: Dorian Zheng
+License-Expression: Apache-2.0
+Requires-Python: >=3.10

boxlite-0.4.0.dev0.dist-info/RECORD

@@ -0,0 +1,20 @@
+boxlite-0.4.0.dev0.dist-info/METADATA,sha256=zW8vWdMNjl-XKLNWjJwEzRkHMc_QA8nXfDLU2lrnwmM,294
+boxlite-0.4.0.dev0.dist-info/WHEEL,sha256=VaEj7o-foDEMacawJ0zlUcxv1TNSymopNT-bNjt0dO8,105
+boxlite/__init__.py,sha256=2wYQEKJc86jXJIwWmIX1s1OiE3FcRs6k29NzCikcm74,1990
+boxlite/boxlite.cpython-311-darwin.so,sha256=_fmnNuqeB7dGl2YIv3mdPFBcXxKCwDQhYAlkl9bfFUk,14824912
+boxlite/browserbox.py,sha256=UX4yxZsnbFHgyLhS9-OC58AG1pecHpUwbxlO6leiV98,4477
+boxlite/codebox.py,sha256=buppZbGh2_jd5syCXx-xFUMQWvo7DRAMXo5unEAgIZY,3677
+boxlite/computerbox.py,sha256=bMFGyK2Gl0w3sw3TJmF6Cl5u2GlaMhSC4WVVbHMGsMg,10566
+boxlite/constants.py,sha256=lIQkb5AHiqef_q9g23szDdzuCNpY8xBWSD0qD52Oc-U,615
+boxlite/errors.py,sha256=vuW2uZvkrX9GGvE3SKIogO8r1rBxUplit_3F2CSxglg,957
+boxlite/exec.py,sha256=UWoLBnKUPx93ueHC2E3KVU7evaj06TIb1pHhuShZwbM,507
+boxlite/interactivebox.py,sha256=4Ffaf-u7m46bIRgHQ61qcLbmgWgUFkmQDLxXykzNy3g,10598
+boxlite/runtime/boxlite-guest,sha256=oA6QuMwIKzrjR8h4fvCz3cjJ3o-nlig-vL7WrvoCSuo,11902344
+boxlite/runtime/boxlite-shim,sha256=ywn1nEDsij6TtG_T9m82Zzw18DlYxDH-6Xu0RIqDsLk,3264976
+boxlite/runtime/debugfs,sha256=DnAkd6bJsxf723TgoVhQOme1b3tZWCcCf5VLUWoY4sc,662328
+boxlite/runtime/libgvproxy.dylib,sha256=irddG9i5EMEowq0rTIMfdWDdmp_m0qZ2zdHvf5lQH0s,10809824
+boxlite/runtime/libkrun.1.15.1.dylib,sha256=jLbXTo2OKkBXZ_DkixypJ2yk0hcKFJeYL9y3globcgc,3960400
+boxlite/runtime/libkrunfw.4.dylib,sha256=cRy63u5WT5twkeR2bHrRCZwcw7uidbeSs_bTCaKb-tA,21979472
+boxlite/runtime/mke2fs,sha256=MscZ6oepZxGLq-sC7o5bLEwRkzzYFLKWhMsNr4T8rVY,578008
+boxlite/simplebox.py,sha256=OIuoEhorcJMefc1_Bc-5RkWvytTg-0V-5joD9EZMqiQ,6497
+boxlite-0.4.0.dev0.dist-info/RECORD,,

boxlite-0.4.0.dev0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.10.2)
+Root-Is-Purelib: false
+Tag: cp311-cp311-macosx_14_0_arm64