feat: added hopx provider

README.md

@@ -9,7 +9,7 @@ Universal library for AI code execution sandboxes.
 
 `sandboxes` provides a unified interface for sandboxed code execution across multiple providers:
 
-- **Current providers**: E2B, Modal, Daytona
+- **Current providers**: E2B, Modal, Daytona, Hopx
 - **Experimental**: Cloudflare (requires self-hosted Worker deployment)
 
 Write your code once and switch between providers with a single line change, or let the library automatically select a provider.
@@ -351,6 +351,7 @@ The library automatically detects available providers from environment variables
 export E2B_API_KEY="..."
 export MODAL_TOKEN_ID="..."  # Or use `modal token set`
 export DAYTONA_API_KEY="..."
+export HOPX_API_KEY="hopx_live_<keyId>.<secret>"
 export CLOUDFLARE_SANDBOX_BASE_URL="https://your-worker.workers.dev"
 export CLOUDFLARE_API_TOKEN="..."
 ```
@@ -372,8 +373,9 @@ When you call `Sandbox.create()` or `run()`, the library checks for providers in
 
 1. **Daytona** - Looks for `DAYTONA_API_KEY`
 2. **E2B** - Looks for `E2B_API_KEY`
-3. **Modal** - Looks for `~/.modal.toml` or `MODAL_TOKEN_ID`
-4. **Cloudflare** *(experimental)* - Looks for `CLOUDFLARE_SANDBOX_BASE_URL` + `CLOUDFLARE_API_TOKEN`
+3. **Hopx** - Looks for `HOPX_API_KEY`
+4. **Modal** - Looks for `~/.modal.toml` or `MODAL_TOKEN_ID`
+5. **Cloudflare** *(experimental)* - Looks for `CLOUDFLARE_SANDBOX_BASE_URL` + `CLOUDFLARE_API_TOKEN`
 
 **The first provider with valid credentials becomes the default.** Cloudflare requires deploying your own Worker.
 
@@ -412,11 +414,12 @@ from sandboxes import Sandbox
 # Configure providers programmatically
 Sandbox.configure(
     e2b_api_key="your-key",
+    hopx_api_key="hopx_live_<keyId>.<secret>",
     cloudflare_config={
         "base_url": "https://your-worker.workers.dev",
         "api_token": "your-token",
     },
-    default_provider="e2b"
+    default_provider="hopx"
 )
 ```
 
@@ -429,6 +432,7 @@ from sandboxes.providers import (
     E2BProvider,
     ModalProvider,
     DaytonaProvider,
+    HopxProvider,
     CloudflareProvider,
 )
 
@@ -441,6 +445,9 @@ provider = ModalProvider()
 # Daytona - Uses DAYTONA_API_KEY env var
 provider = DaytonaProvider()
 
+# Hopx - Uses HOPX_API_KEY env var
+provider = HopxProvider()
+
 # Cloudflare - Requires base_url and token
 provider = CloudflareProvider(
     base_url="https://your-worker.workers.dev",
@@ -452,6 +459,7 @@ Each provider requires appropriate authentication:
 - **E2B**: Set `E2B_API_KEY` environment variable
 - **Modal**: Run `modal token set` to configure
 - **Daytona**: Set `DAYTONA_API_KEY` environment variable
+- **Hopx**: Set `HOPX_API_KEY` environment variable (format: `hopx_live_<keyId>.<secret>`)
 - **Cloudflare** *(experimental)*: Deploy the [Cloudflare sandbox Worker](https://github.com/cloudflare/sandbox-sdk) and set `CLOUDFLARE_SANDBOX_BASE_URL`, `CLOUDFLARE_API_TOKEN`, and (optionally) `CLOUDFLARE_ACCOUNT_ID`
 
 > **Cloudflare setup tips (experimental)**
@@ -479,6 +487,7 @@ async def main():
     manager.register_provider("e2b", E2BProvider, {})
     manager.register_provider("modal", ModalProvider, {})
     manager.register_provider("daytona", DaytonaProvider, {})
+    manager.register_provider("hopx", HopxProvider, {})
     manager.register_provider(
         "cloudflare",
         CloudflareProvider,

docs/hopx-api-reference.md

@@ -0,0 +1,119 @@
+# Hopx API Reference
+
+This document contains the full API reference for implementing the Hopx provider.
+
+## Authentication
+
+Hopx uses **API keys** for request authentication. Keys follow the format `hopx_live_<keyId>.<secret>` and are obtained from the dashboard.
+
+**Supported methods:**
+- `X-API-Key` header (recommended)
+- `Authorization: Bearer` header
+- Environment variable (`HOPX_API_KEY`)
+
+Keys should never be hardcoded; use environment variables or secrets managers instead.
+
+## API Structure
+
+The platform provides two main API sections:
+
+**Lifecycle API** (`/v1/sandboxes`, `/v1/templates`): Manage sandbox creation, deletion, listing, and state transitions (start, stop, pause, resume).
+
+**VM Agent API** (`https://{sandbox_id}.hopx.dev`): Interact with running sandboxes for code execution, file operations, and system management.
+
+## Core Endpoints
+
+### Sandbox Management
+- `POST /v1/sandboxes` - Create sandbox from template
+- `GET /v1/sandboxes` - List all sandboxes (with filtering)
+- `GET /v1/sandboxes/{id}` - Get sandbox details
+- `DELETE /v1/sandboxes/{id}` - Delete sandbox
+- `POST /v1/sandboxes/{id}/{action}` - Control operations (start, stop, pause, resume)
+
+### Template Operations
+- `GET /v1/templates` - List templates
+- `GET /v1/templates/{id}` - Get template details
+- `POST /v1/templates/build` - Create custom template
+- `DELETE /v1/templates/{id}` - Delete template
+
+### Code Execution
+- `POST {sandbox_host}/execute` - Execute code
+- `POST {sandbox_host}/execute/rich` - Execute with rich outputs (plots, DataFrames)
+- `POST {sandbox_host}/commands/run` - Run shell commands
+- `GET {sandbox_host}/execute/processes` - List processes
+- `POST {sandbox_host}/execute/kill/{id}` - Terminate process
+
+### File Operations
+- `GET /files/read` - Read file content
+- `POST /files/write` - Create/update file
+- `GET /files/list` - List directory contents
+- `GET /files/download` - Download file
+- `POST /files/upload` - Upload file (multipart/form-data)
+
+### Additional Features
+- **Environment Variables**: GET, PUT, PATCH, DELETE operations on `/env`
+- **Metrics**: `GET /metrics/snapshot` and health checks
+- **Cache Management**: Get stats and clear cache
+- **Desktop Automation**: VNC access, screenshots, mouse/keyboard control
+- **WebSocket Support**: Real-time streaming for code execution, terminal, and file watching
+
+## Request/Response Format
+
+**Headers:**
+```
+Content-Type: application/json
+X-API-Key: your_api_key_here
+```
+
+**Success responses** return JSON with resource data; **error responses** include `error`, `code`, and optional `message` fields.
+
+## Supported Languages
+
+- Python
+- JavaScript/Node.js
+- Bash
+- Go
+
+## Rate Limiting
+
+Rate limits vary by organization. Limits are communicated via headers:
+- `X-RateLimit-Limit`
+- `X-RateLimit-Remaining`
+- `X-RateLimit-Reset`
+
+Template building is limited to 10 builds/hour and 50 builds/day by default.
+
+## Special Features
+
+**Memory Snapshots**: Templates use memory snapshots for sub-100ms boot times.
+
+**Sandbox States**: running, stopped, paused, creating.
+
+**Rich Output Support**: Captures plots, DataFrames, and other formatted outputs.
+
+**Real-time Streaming**: WebSocket endpoints enable live code execution and file system monitoring.
+
+**Environment Isolation**: Sandboxes support custom resource allocation and internet access control.
+
+## Implementation Notes for Provider
+
+### Base URL
+The main API base URL should be configurable, likely: `https://api.hopx.dev`
+
+### Two-Level API Access
+1. **Control Plane**: `https://api.hopx.dev/v1/*` - Lifecycle management
+2. **Data Plane**: `https://{sandbox_id}.hopx.dev/*` - Code execution and file operations
+
+### Key Differences from Other Providers
+- Uses HTTP REST API (like Cloudflare provider)
+- Requires template selection for sandbox creation
+- Supports multiple sandbox states (running, stopped, paused)
+- Has separate endpoints for lifecycle vs execution
+- Supports rich output formats (plots, DataFrames)
+
+### Recommended Implementation Approach
+1. Use `aiohttp` for async HTTP requests (consistent with Cloudflare provider)
+2. Store base URL and API key in config
+3. Track sandbox state transitions (creating → running → stopped)
+4. Implement streaming execution using WebSocket or SSE
+5. Support template-based creation with default template fallback

pyproject.toml

@@ -29,6 +29,7 @@ dependencies = [
     "modal>=1.1.4",
     "e2b>=2.0.0",
     "daytona>=0.103.0",
+    "hopx-ai>=0.1.19",
     "httpx>=0.27.0",
 ]
 
@@ -42,6 +43,9 @@ e2b = [
 modal = [
     "modal==1.1.4",  # Latest stable version
 ]
+hopx = [
+    "hopx-ai>=0.1.19",  # Official Hopx SDK for secure cloud sandboxes
+]
 # vercel = [
 #     "vercel-sdk>=0.1.0",  # When available
 # ]
@@ -52,6 +56,7 @@ all = [
     "daytona==0.103.0",
     "e2b>=2.0.0",
     "modal==1.1.4",
+    "hopx-ai>=0.1.19",
 ]
 dev = [
     "pytest>=7.4.0",

sandboxes/providers/__init__.py

@@ -33,6 +33,13 @@
 except ImportError:
     pass
 
+try:
+    from .hopx import HopxProvider
+
+    _providers["hopx"] = HopxProvider
+except ImportError:
+    pass
+
 try:
     from .vercel import VercelProvider