Add Blaxel provider support and update documentation

API_FEATURES.md

@@ -28,6 +28,7 @@ Grainchain provides a unified Python interface for interacting with various sand
 
 | Provider | Status | Specialization |
 |----------|--------|----------------|
+| **Blaxel** | ✅ Production Ready | Custom Docker images, automatic snapshots, 25ms startup |
 | **E2B** | ✅ Production Ready | Custom Docker images, development environments |
 | **Morph** | ✅ Production Ready | Memory snapshots, instant state management |
 | **Daytona** | ✅ Production Ready | Cloud development workspaces |
@@ -239,6 +240,7 @@ async with Sandbox(provider="e2b") as sandbox:
 | Provider | Snapshot Type | Creation Speed | Restoration Speed | Preserves Processes | Notes |
 |----------|---------------|----------------|-------------------|-------------------|-------|
 | **Morph** | Memory | <250ms | <500ms | ✅ Yes | True pause/resume functionality |
+| **Blaxel** | Memory + Filesystem | 1-5s | 25-50ms | ✅ Yes | Automatic state management |
 | **E2B** | Filesystem | 2-10s | 5-15s | ❌ No | Template-based restoration |
 | **Local** | Filesystem | 1-5s | 1-3s | ❌ No | Directory-based snapshots |
 | **Daytona** | Filesystem | 3-8s | 5-12s | ❌ No | Workspace state preservation |
@@ -284,6 +286,86 @@ async with Sandbox(provider="morph") as sandbox:
 
 ### Current Docker Support by Provider
 
+#### Blaxel Provider - Full Custom Docker Support ✅
+
+**Capabilities:**
+- Custom Docker images with automatic image management
+- Configurable memory allocation
+- Regional deployment options
+- Port forwarding support
+- TTL (Time To Live) configuration for sandbox lifecycle
+- Workspace-based authentication
+
+**Configuration:**
+```python
+config = SandboxConfig(
+    image="blaxel/prod-base:latest",
+    provider_config={
+        "name": "my-custom-sandbox",      # Custom sandbox name
+        "memory": 8192,                   # Memory in MB (default: 4096)
+        "region": "us-pdx-1",             # Deployment region
+        "ttl": "2h",                      # TTL with human-readable format (optional)
+        "ttl_idle": "30m",                # Delete after 30 minutes of inactivity (optional)
+        "expires": "2025-12-31T23:59:59Z", # Absolute expiration date (optional)
+        "ports": [                        # Port configuration
+            {"target": 3000, "protocol": "HTTP"},
+            {"target": 8080, "protocol": "HTTP"}
+        ],
+        "api_key": "your-api-key",        # API key (optional if using CLI auth)
+        "workspace": "your-workspace"     # Workspace name (optional if using CLI auth)
+    }
+)
+
+async with Sandbox(provider="blaxel", config=config) as sandbox:
+    # Runs in your configured Docker environment
+    result = await sandbox.execute("python --version")
+```
+
+**TTL (Time To Live) Configuration:**
+
+Blaxel supports three types of lifecycle management:
+
+1. **`ttl`** - Maximum lifetime of the sandbox
+   - Accepts human-readable formats: `"30s"`, `"10m"`, `"2h"`, `"1d"`
+   - Also accepts seconds as an integer for backwards compatibility
+   - Sandbox terminates after this duration from creation
+
+2. **`ttl_idle`** - Idle timeout for automatic cleanup
+   - Accepts human-readable formats: `"30m"`, `"1h"`, `"2h"`
+   - Sandbox terminates after this duration of inactivity
+   - Useful for development environments that should clean up when unused
+
+3. **`expires`** - Absolute expiration date
+   - ISO 8601 format: `"2025-10-07T14:53:46Z"`
+   - Sandbox terminates at this specific date/time
+   - Useful for time-limited access or scheduled cleanup
+
+**Examples:**
+```python
+# Short-lived CI/CD pipeline (10 minutes)
+ci_config = {"ttl": "10m"}
+
+# Development environment with idle cleanup (2 hours active, 30 min idle)
+dev_config = {"ttl": "2h", "ttl_idle": "30m"}
+
+# Time-limited demo until end of day
+demo_config = {"expires": "2025-10-07T17:00:00Z"}
+```
+
+**Authentication Methods:**
+1. **CLI Authentication (Recommended for local development):**
+   ```bash
+   bl login YOUR-WORKSPACE
+   ```
+
+2. **Environment Variables:**
+   ```bash
+   export BL_API_KEY='your-api-key'
+   export BL_WORKSPACE='your-workspace'
+   ```
+
+3. **Provider Config (Shown above)**
+
 #### E2B Provider - Full Custom Docker Support ✅
 
 **Capabilities:**
@@ -439,6 +521,7 @@ async with Sandbox(provider="docker", config=config) as sandbox:
 
 | Provider | Docker Support | Custom Images | Dockerfile | Base Images | Status |
 |----------|----------------|---------------|------------|-------------|--------|
+| **Blaxel** | ✅ Full | ✅ Yes | ✅ Yes | ✅ Multiple | Production |
 | **E2B** | ✅ Full | ✅ Yes | ✅ e2b.Dockerfile | ✅ Multiple | Production |
 | **Morph** | ✅ Partial | ❌ No | ❌ No | ✅ Curated | Production |
 | **Modal** | ✅ Full | ✅ Yes | ✅ Programmatic | ✅ Registry | Production |
@@ -450,25 +533,26 @@ async with Sandbox(provider="docker", config=config) as sandbox:
 
 ### Feature Support Matrix
 
-| Feature | E2B | Morph | Daytona | Modal | Local | Docker* |
-|---------|-----|-------|---------|-------|-------|---------|
-| **Core Execution** | ✅ | ✅ | ✅ | ✅ | ✅ | 🚧 |
-| **File Operations** | ✅ | ✅ | ✅ | ✅ | ✅ | 🚧 |
-| **Filesystem Snapshots** | ✅ | ❌ | ✅ | ✅ | ✅ | 🚧 |
-| **Memory Snapshots** | ❌ | ✅ | ❌ | ❌ | ❌ | 🚧 |
-| **Terminate/Wake-up** | ❌ | ✅ | ❌ | ❌ | ❌ | 🚧 |
-| **Custom Docker** | ✅ | ❌ | ❌ | ✅ | ❌ | 🚧 |
-| **Base Images** | ✅ | ✅ | ✅ | ✅ | ❌ | 🚧 |
-| **Resource Limits** | ✅ | ✅ | ✅ | ✅ | ❌ | 🚧 |
-| **Persistent Storage** | ✅ | ✅ | ✅ | ✅ | ✅ | 🚧 |
-| **Network Access** | ✅ | ✅ | ✅ | ✅ | ✅ | 🚧 |
+| Feature | Blaxel | E2B | Morph | Daytona | Modal | Local | Docker* |
+|---------|--------|-----|-------|---------|-------|-------|---------|
+| **Core Execution** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 🚧 |
+| **File Operations** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 🚧 |
+| **Filesystem Snapshots** | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | 🚧 |
+| **Memory Snapshots** | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | 🚧 |
+| **Terminate/Wake-up** | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | 🚧 |
+| **Custom Docker** | ✅ | ✅ | ❌ | ❌ | ✅ | ❌ | 🚧 |
+| **Base Images** | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | 🚧 |
+| **Resource Limits** | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | 🚧 |
+| **Persistent Storage** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 🚧 |
+| **Network Access** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 🚧 |
 
 *Docker provider features are planned
 
 ### Performance Characteristics
 
 | Provider | Startup Time | Execution Overhead | Snapshot Creation | Snapshot Restoration |
 |----------|--------------|-------------------|-------------------|---------------------|
+| **Blaxel** | 1-5s | Minimal | Automatic | 25-50ms |
 | **E2B** | 5-15s | Low | 2-10s | 5-15s |
 | **Morph** | <250ms | Minimal | <250ms | <500ms |
 | **Daytona** | 10-30s | Low | 3-8s | 5-12s |
@@ -479,6 +563,7 @@ async with Sandbox(provider="docker", config=config) as sandbox:
 
 | Provider | Pricing Model | Cost Efficiency | Free Tier |
 |----------|---------------|-----------------|-----------|
+| **Blaxel** | Usage-based | High for production | ✅ Available |
 | **E2B** | Per-minute usage | High for development | ✅ Available |
 | **Morph** | Per-instance + snapshots | High for long-running | ❌ Paid only |
 | **Daytona** | Workspace-based | Medium | ✅ Available |
@@ -560,7 +645,7 @@ async def snapshot_workflow():
 
 ```python
 async def compare_providers():
-    providers = ["local", "e2b", "morph"]
+    providers = ["local", "blaxel", "e2b", "morph"]
     results = {}
 
     for provider in providers:
@@ -620,22 +705,23 @@ Choose your provider based on your needs:
 
 📊 **Performance Priority**
 ├── Fastest startup → Local (development only)
-├── Fastest snapshots → Morph (<250ms)
-└── Balanced performance → E2B or Modal
+├── Fastest snapshots → Blaxel (automatic)
+└── Balanced performance → Blaxel, E2B or Modal
 
 🔧 **Feature Requirements**
 ├── Memory snapshots → Morph (only option)
-├── Custom Docker → E2B or Modal
+├── Custom Docker → Blaxel, E2B or Modal
+├── TTL configuration → Blaxel (automatic cleanup)
 ├── Long-running processes → Morph (terminate/wake-up)
 └── Simple file operations → Any provider
 
 💰 **Cost Considerations**
-├── Free development → Local, E2B (free tier), Modal (free tier)
-├── Production efficiency → Morph (pay for what you use)
+├── Free development → Local, Blaxel (free tier), E2B (free tier), Modal (free tier)
+├── Production efficiency → Blaxel or Morph (pay for what you use)
 └── Batch processing → Modal (serverless pricing)
 
 🏗️ **Use Case Specific**
-├── CI/CD pipelines → E2B (Docker support)
+├── CI/CD pipelines → Blaxel or E2B (Docker support with TTL)
 ├── Interactive development → Morph (memory snapshots)
 ├── Data processing → Modal (scalable compute)
 ├── Local testing → Local (no overhead)
@@ -712,6 +798,7 @@ Grainchain provides a powerful, unified interface for sandbox management with:
 ✅ **Type-safe** Python interface with async support
 
 **Key Takeaways:**
+- Use **Blaxel** for production-ready cloud sandboxes with automatic snapshots and custom Docker images
 - Use **Morph** for memory snapshots and instant state management
 - Use **E2B** for custom Docker environments and development
 - Use **Modal** for scalable compute with custom images

BENCHMARKING.md

@@ -11,7 +11,7 @@ Grainchain now includes powerful analysis capabilities to help you make data-dri
 ```bash
 # Run benchmarks and analyze results
 grainchain benchmark --provider all
-grainchain analysis compare --provider1 local --provider2 e2b --chart
+grainchain analysis compare --provider1 local --provider2 blaxel --chart
 grainchain analysis report --format html --include-charts
 ```
 
@@ -90,6 +90,7 @@ grainchain benchmark --provider local
 
 1. **Try other providers** (requires API keys):
    ```bash
+   grainchain benchmark --provider blaxel
    grainchain benchmark --provider e2b
    grainchain benchmark --provider daytona
    grainchain benchmark --provider morph
@@ -170,6 +171,10 @@ python benchmarks/scripts/grainchain_benchmark.py --config my_config.json
 Set up your provider credentials:
 
 ```bash
+# Blaxel Provider (optional - can use CLI auth)
+BL_API_KEY=your_blaxel_api_key_here
+BL_WORKSPACE=your_workspace_here
+
 # E2B Provider
 E2B_API_KEY=your_e2b_api_key_here
 E2B_TEMPLATE=base

INTEGRATION.md

@@ -288,6 +288,8 @@ class AppConfig:
     default_provider: str = "local"
     default_timeout: int = 300
     max_concurrent_sandboxes: int = 10
+    blaxel_api_key: str = ""
+    blaxel_workspace: str = ""
     e2b_api_key: str = ""
     morph_api_key: str = ""
     daytona_api_key: str = ""
@@ -299,6 +301,8 @@ class AppConfig:
             default_provider=os.getenv("GRAINCHAIN_DEFAULT_PROVIDER", "local"),
             default_timeout=int(os.getenv("GRAINCHAIN_DEFAULT_TIMEOUT", "300")),
             max_concurrent_sandboxes=int(os.getenv("GRAINCHAIN_MAX_CONCURRENT", "10")),
+            blaxel_api_key=os.getenv("BL_API_KEY", ""),
+            blaxel_workspace=os.getenv("BL_WORKSPACE", ""),
             e2b_api_key=os.getenv("E2B_API_KEY", ""),
             morph_api_key=os.getenv("MORPH_API_KEY", ""),
             daytona_api_key=os.getenv("DAYTONA_API_KEY", ""),
@@ -392,6 +396,11 @@ class RobustExecutor:
 
 # Usage
 executor = RobustExecutor(max_retries=3)
+
+# Try with Blaxel
+result = await executor.execute_with_retry("print('Hello')", provider="blaxel")
+
+# Try with E2B
 result = await executor.execute_with_retry("print('Hello')", provider="e2b")
 ```
 

MANIFESTO.md

@@ -14,7 +14,7 @@ Today, developers face an impossible choice: commit to a single sandbox provider
 
 ## The Problem We're Solving
 
-The explosion of sandbox providers—E2B, Modal, Daytona, Morph, and countless others—represents incredible innovation in cloud computing. But this innovation comes with a cost:
+The explosion of sandbox providers—Blaxel, E2B, Modal, Daytona, Morph, and countless others—represents incredible innovation in cloud computing. But this innovation comes with a cost:
 
 - **Developers are trapped** by vendor-specific APIs
 - **Innovation is stifled** by the fear of choosing the wrong provider
@@ -26,7 +26,7 @@ The explosion of sandbox providers—E2B, Modal, Daytona, Morph, and countless o
 ## Our Principles
 
 ### 1. **Provider Agnostic by Design**
-Write once, run anywhere. Your code should work seamlessly across E2B, Modal, Daytona, Morph, or any future provider that emerges.
+Write once, run anywhere. Your code should work seamlessly across Blaxel, E2B, Modal, Daytona, Morph, or any future provider that emerges.
 
 ### 2. **Simplicity Over Complexity**
 A unified API shouldn't mean a complicated API. We believe in clean, intuitive interfaces that make the complex simple.
@@ -64,7 +64,7 @@ async with Sandbox() as sandbox:
 ```
 
 ### ✅ **Provider Flexibility**
-Switch between E2B, Modal, Daytona, Morph, and Local providers with a single configuration change.
+Switch between Blaxel, E2B, Modal, Daytona, Morph, and Local providers with a single configuration change.
 
 ### ✅ **Production Ready**
 Built with async/await, comprehensive error handling, and battle-tested patterns.
@@ -90,7 +90,7 @@ But we're just getting started.
 
 ### **Phase 1: Foundation** ✅
 - Core API design and implementation
-- Support for major providers (E2B, Modal, Daytona, Morph, Local)
+- Support for major providers (Blaxel, E2B, Modal, Daytona, Morph, Local)
 - Production-ready packaging and distribution
 
 ### **Phase 2: Ecosystem** 🚧