dynamiq-sandboxes 0.3.0
Python SDK for Dynamiq Sandboxes - Secure code execution, browser automation, and virtual desktops
Requires Python: >=3.9
Keywords: sandbox, code-execution, browser-automation, virtual-desktop, ai-agents, dynamiq, code-interpreter, cloud-sandbox

# Dynamiq Sandboxes

[![PyPI version](https://badge.fury.io/py/dynamiq-sandboxes.svg)](https://pypi.org/project/dynamiq-sandboxes/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

Python SDK for [Dynamiq Sandboxes](https://sandboxes.getdynamiq.ai) — secure, isolated environments for code execution, browser automation, and virtual desktops.

Built for AI agents and automation pipelines. Part of the [Dynamiq](https://github.com/dynamiq-ai/dynamiq) ecosystem.

## Installation

```bash
pip install dynamiq-sandboxes
```

## Quick Start

```bash
export DYNAMIQ_API_KEY="your-api-key"
```

```python
from dynamiq_sandboxes import Sandbox

sandbox = Sandbox.create(template="python")

result = sandbox.execute_command("echo 'Hello from the sandbox!'")
print(result["stdout"])  # Hello from the sandbox!

sandbox.close()
```

## Code Sandboxes

Isolated execution environments with Python, Node.js, and shell support.

```python
from dynamiq_sandboxes import Sandbox

sandbox = Sandbox.create(template="python", timeout=3600)

# Execute shell commands (auto-wrapped in /bin/bash)
result = sandbox.execute_command("echo hello && ls /")
print(result["stdout"])
print(result["exit_code"])  # 0

# Run Python code directly
output = sandbox.run_code("print(2 + 2)", language="python")
print(output["stdout"])  # 4

# Explicit args mode (no shell wrapping)
result = sandbox.execute_command("python3", args=["-c", "print('direct')"])

# Per-command environment variables
result = sandbox.execute_command("echo $MY_VAR", env={"MY_VAR": "hello"})
print(result["stdout"])  # hello

# Background execution
result = sandbox.execute_command("sleep 60", background=True)

# File operations
sandbox.filesystem.write("/app/config.json", '{"key": "value"}')
content = sandbox.filesystem.read("/app/config.json")
print(content)  # {"key": "value"}

files = sandbox.filesystem.list("/app")
for f in files:
    print(f"{f.name}  {f.size}B  ({f.type})")

# Directory operations
sandbox.filesystem.mkdir("/app/data")
sandbox.filesystem.copy("/app/config.json", "/app/data/config.json")
sandbox.filesystem.move("/app/data/config.json", "/app/data/settings.json")
sandbox.filesystem.remove("/app/data", recursive=True)

# Upload / download files
sandbox.filesystem.upload("local_file.py", "/app/script.py")
sandbox.filesystem.download("/app/output.csv", "local_output.csv")

# Check file existence and metadata
if sandbox.filesystem.exists("/app/script.py"):
    info = sandbox.filesystem.stat("/app/script.py")
    print(f"{info.name}: {info.size} bytes")

# Resource metrics
metrics = sandbox.metrics()
print(f"CPU: {metrics['cpu']['usage_percent']}%")

# Extend session timeout
sandbox.extend_timeout(3600)  # Add 1 hour
sandbox.set_timeout(3600)     # Alias — same as extend_timeout

sandbox.close()
```

## Reconnecting to Sandboxes

```python
from dynamiq_sandboxes import Sandbox

# Connect to an existing sandbox (auto-resumes if paused)
sandbox = Sandbox.connect("sbx-abc123")
result = sandbox.execute_command("whoami")
print(result["stdout"])
```

## Browser Automation

Headless Chromium with CDP access, screenshots, scraping, and live streaming.

```python
from dynamiq_sandboxes import Browser

browser = Browser.create(
    stealth=True,            # Anti-detection mode
    viewport_width=1920,
    viewport_height=1080,
)

# Navigate to pages
browser.navigate("https://example.com")

# Take screenshots
result = browser.screenshot(full_page=True)
# result["image"] is a data URI: data:image/png;base64,...
# result["width"], result["height"]

# Scrape page content
scrape = browser.scrape(format="text")
print(scrape["content"])

# Execute JavaScript
title = browser.execute_script("() => document.title")
url = browser.execute_script("() => window.location.href")

# Navigation history
browser.go_back()
browser.go_forward()
browser.reload()

# Browser context (cookies, localStorage)
ctx = browser.get_context()
print(ctx)

# Console logs and network requests
logs = browser.get_logs()
requests = browser.get_network_requests()
har = browser.export_har()

# Live streaming info (for embedding in UI)
live = browser.get_live_view()
print(live["stream_url"])     # WebSocket stream URL
print(live["livekit_url"])    # LiveKit WebRTC URL
print(live["livekit_token"])  # JWT token for viewer

browser.close()
```

### CDP Access (Playwright / Puppeteer)

Every browser session exposes a **Chrome DevTools Protocol** WebSocket that works with any CDP-compatible tool:

```python
# Get the CDP URL from the sandbox
browser = Browser.create(stealth=True)
cdp_url = browser.data["cdp_websocket_url"]
# wss://api.sandboxes.getdynamiq.ai/v1/browser/sessions/{id}/cdp
```

**Playwright (Python):**

```python
from playwright.async_api import async_playwright

async with async_playwright() as p:
    b = await p.chromium.connect_over_cdp(
        cdp_url,
        headers={"X-API-Key": "your-api-key"},
    )
    page = b.contexts[0].pages[0]

    await page.goto("https://example.com")
    print(await page.title())
    await page.screenshot(path="screenshot.png")
```

**Puppeteer (Node.js):**

```javascript
const browser = await puppeteer.connect({
  browserWSEndpoint: cdpUrl,
  headers: { "X-API-Key": "your-api-key" },
});
const page = (await browser.pages())[0];
await page.goto("https://example.com");
await page.screenshot({ path: "screenshot.png" });
```

## Virtual Desktops

Full Ubuntu desktop with XFCE, mouse/keyboard control, and VNC streaming.

```python
from dynamiq_sandboxes import Desktop

desktop = Desktop.create(template="ubuntu-desktop")

# Take screenshots
result = desktop.screenshot()
# result["image"] is a data URI, result["width"], result["height"]

# Launch applications
desktop.launch(application="xfce4-terminal")
desktop.launch(application="firefox")

# Mouse control
desktop.mouse_click(x=500, y=300)
desktop.mouse_click(x=500, y=300, button="right")     # Right click
desktop.mouse_click(x=500, y=300, double_click=True)   # Double click
desktop.mouse_move(x=100, y=200)
desktop.mouse_scroll(x=500, y=300, delta_x=0, delta_y=-3)
desktop.mouse_drag(start_x=100, start_y=100, end_x=300, end_y=300)

# Keyboard input
desktop.keyboard_type(text="Hello, World!")
desktop.keyboard_press(keys=["Return"])
desktop.keyboard_press(keys=["ctrl", "c"])     # Hotkey combo
desktop.keyboard_press(keys=["ctrl", "l"])     # Clear terminal

# Open URLs
desktop.open(path="https://example.com")

# Get cursor position
cursor = desktop.cursor()
print(f"Cursor at ({cursor['x']}, {cursor['y']})")

# VNC streaming (for embedding in your UI)
stream = desktop.stream_start()
info = desktop.stream_info()
print(f"noVNC URL: {info.get('novnc_url')}")
print(f"WebSocket: {info.get('stream_url')}")

desktop.close()
```

## Network Configuration

```python
from dynamiq_sandboxes import Sandbox, NetworkConfig, ALL_TRAFFIC

# Deny all traffic except specific IPs
sandbox = Sandbox.create(
    template="python",
    network=NetworkConfig(
        deny_out=[ALL_TRAFFIC],
        allow_out=["1.1.1.1", "8.8.8.0/24"],
    ),
)

# Disable internet access entirely
sandbox = Sandbox.create(
    template="python",
    network=NetworkConfig(allow_internet_access=False),
)
```

## Template Builder

```python
from dynamiq_sandboxes import TemplateBuilder, Template

# Build a custom template
template = (
    TemplateBuilder()
    .from_base_image("python:3.11-slim")
    .set_envs({"LANG": "C.UTF-8"})
    .run_cmd("pip install numpy pandas")
    .set_start_cmd("python -m http.server 8080")
    .set_description("Data science sandbox")
)

info = template.build("my-data-science", api_key="your-key")
print(info.template_id)

# List and manage templates
templates = Template.list(api_key="your-key")
for t in templates:
    print(f"{t.name}: {t.status}")
```

## REST API

All SDK methods map to REST API calls:

```bash
# Create a sandbox
curl -X POST https://api.sandboxes.getdynamiq.ai/v1/sandboxes \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template_id": "python", "timeout": 3600}'

# Execute a command
curl -X POST https://api.sandboxes.getdynamiq.ai/v1/sandboxes/{id}/commands \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "echo hello"}'

# Create a browser session
curl -X POST https://api.sandboxes.getdynamiq.ai/v1/browser/sessions \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stealth": true}'

# Create a desktop
curl -X POST https://api.sandboxes.getdynamiq.ai/v1/sandboxes \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template_id": "ubuntu-desktop", "sandbox_type": "desktop"}'
```

## Configuration

| Environment Variable | Description | Default |
|---------------------|-------------|---------|
| `DYNAMIQ_API_KEY` | API key for authentication | Required |
| `DYNAMIQ_API_URL` | API base URL | `https://api.sandboxes.getdynamiq.ai/v1` |

```python
# Or pass directly
sandbox = Sandbox.create(
    template="python",
    api_key="your-api-key",
    base_url="https://api.sandboxes.getdynamiq.ai/v1",
)
```

## API Reference

### Sandbox

| Method | Description |
|--------|-------------|
| `Sandbox.create(template, timeout, vcpu, memory_mb, ...)` | Create a new sandbox |
| `Sandbox.get(sandbox_id)` | Get existing sandbox by ID |
| `Sandbox.connect(sandbox_id, timeout)` | Connect to sandbox (auto-resumes if paused) |
| `Sandbox.list(state, tags, ...)` | List sandboxes with filtering |
| `sandbox.execute_command(command, args, env, working_dir, timeout, background)` | Execute a shell command |
| `sandbox.run_code(code, language, timeout)` | Run code in a language interpreter |
| `sandbox.filesystem.write(path, content)` | Write a file |
| `sandbox.filesystem.read(path)` | Read a file |
| `sandbox.filesystem.list(path)` | List directory contents |
| `sandbox.filesystem.mkdir(path)` | Create directory |
| `sandbox.filesystem.remove(path, recursive)` | Delete file or directory |
| `sandbox.filesystem.exists(path)` | Check if path exists |
| `sandbox.filesystem.stat(path)` | Get file metadata |
| `sandbox.filesystem.copy(src, dst)` | Copy file/directory |
| `sandbox.filesystem.move(src, dst)` | Move/rename file |
| `sandbox.filesystem.upload(local, remote)` | Upload local file |
| `sandbox.filesystem.download(remote, local)` | Download file |
| `sandbox.metrics()` | Get CPU/memory/disk metrics |
| `sandbox.extend_timeout(seconds)` | Extend session lifetime |
| `sandbox.set_timeout(seconds)` | Alias for extend_timeout |
| `sandbox.pause()` | Pause sandbox (preserves state) |
| `sandbox.resume(timeout)` | Resume paused sandbox |
| `sandbox.refresh()` | Refresh sandbox state |
| `sandbox.close()` | Terminate sandbox |

### Browser

| Method | Description |
|--------|-------------|
| `Browser.create(stealth, viewport_width, viewport_height, ...)` | Create browser session |
| `Browser.get(session_id)` | Connect to existing session |
| `browser.navigate(url, wait_until, timeout)` | Navigate to URL |
| `browser.screenshot(format, full_page, quality)` | Capture screenshot |
| `browser.scrape(format, wait_for, timeout)` | Extract page content |
| `browser.execute_script(script)` | Execute JavaScript |
| `browser.go_back()` | Navigate back |
| `browser.go_forward()` | Navigate forward |
| `browser.reload()` | Reload page |
| `browser.get_current_url()` | Get current URL |
| `browser.get_context()` | Get cookies/storage |
| `browser.get_logs()` | Get console logs |
| `browser.get_network_requests()` | Get captured requests |
| `browser.export_har()` | Export HAR archive |
| `browser.get_live_view()` | Get streaming info |
| `browser.send_input(type, x, y, text, ...)` | Send input events |
| `browser.close()` | Close session |

### Desktop

| Method | Description |
|--------|-------------|
| `Desktop.create(template, timeout, ...)` | Create virtual desktop |
| `Desktop.get(desktop_id)` | Connect to existing desktop |
| `desktop.screenshot(format, quality)` | Capture screenshot |
| `desktop.launch(application, args)` | Launch application |
| `desktop.mouse_click(x, y, button, double_click)` | Mouse click |
| `desktop.mouse_move(x, y)` | Move cursor |
| `desktop.mouse_scroll(x, y, delta_x, delta_y)` | Scroll |
| `desktop.mouse_drag(start_x, start_y, end_x, end_y)` | Drag |
| `desktop.keyboard_type(text)` | Type text |
| `desktop.keyboard_press(keys, duration_ms)` | Press keys |
| `desktop.cursor()` | Get cursor position |
| `desktop.open(path)` | Open file/URL |
| `desktop.stream_start()` | Start VNC stream |
| `desktop.stream_stop()` | Stop VNC stream |
| `desktop.stream_info()` | Get stream status |
| `desktop.list_windows()` | List windows |
| `desktop.close()` | Close desktop |

## Error Handling

```python
from dynamiq_sandboxes import (
    Sandbox, APIError, AuthenticationError,
    NotFoundError, RateLimitError, TimeoutError,
)

try:
    sandbox = Sandbox.create(template="python")
    result = sandbox.execute_command("echo hello")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError:
    print("Rate limited, retry later")
except TimeoutError:
    print("Request timed out")
except APIError as e:
    print(f"API error: {e}")
```

## Requirements

- Python 3.9+
- An active [Dynamiq](https://sandboxes.getdynamiq.ai) account

## Links

- **Dashboard**: [sandboxes.getdynamiq.ai](https://sandboxes.getdynamiq.ai)
- **Dynamiq Framework**: [github.com/dynamiq-ai/dynamiq](https://github.com/dynamiq-ai/dynamiq)
- **Issues**: [GitHub Issues](https://github.com/dynamiq-ai/dynamiq/issues)

## License

Apache 2.0