{"id":38852273,"url":"https://github.com/codegen-sh/grainchain","last_synced_at":"2026-01-17T14:13:38.417Z","repository":{"id":297150016,"uuid":"993861446","full_name":"codegen-sh/grainchain","owner":"codegen-sh","description":"Langchain for sandboxes","archived":false,"fork":false,"pushed_at":"2025-07-06T18:40:19.000Z","size":959,"stargazers_count":1,"open_issues_count":5,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-06T19:40:46.014Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codegen-sh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-31T17:20:51.000Z","updated_at":"2025-07-06T18:40:24.000Z","dependencies_parsed_at":"2025-06-04T10:08:57.725Z","dependency_job_id":"eaef564b-6844-4d23-af42-414760057fd4","html_url":"https://github.com/codegen-sh/grainchain","commit_stats":null,"previous_names":["codegen-sh/grainchain"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/codegen-sh/grainchain","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codegen-sh%2Fgrainchain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codegen-sh%2Fgrainchain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codegen-sh%2Fgrainchain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codegen-sh%2Fgrainchain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codegen-sh","download_url":"https://codeload.github.com/codegen-sh/grainchain/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codegen-sh%2Fgrainchain/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28509941,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T13:38:16.342Z","status":"ssl_error","status_checked_at":"2026-01-17T13:37:44.060Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-17T14:13:38.354Z","updated_at":"2026-01-17T14:13:38.410Z","avatar_url":"https://github.com/codegen-sh.png","language":"Python","readme":"# Grainchain 🏜️\n\n\u003e **Langchain for Sandboxes** - A unified Python interface for sandbox providers\n\nGrainchain provides a clean, consistent API for interacting with various sandbox providers, enabling developers to write code once and run it across multiple sandbox environments. Just like Langchain abstracts LLM providers, Grainchain abstracts sandbox providers.\n\n## 🚀 Quick Start\n\n```python\nimport asyncio\nfrom grainchain import Sandbox\n\nasync def main():\n    # Create a sandbox with the default provider\n    async with Sandbox() as sandbox:\n        # Execute code\n        result = await sandbox.execute(\"echo 'Hello, Grainchain!'\")\n        print(result.stdout)  # \"Hello, Grainchain!\"\n\n        # Upload and run a Python script\n        await sandbox.upload_file(\"script.py\", \"print('Hello from Python!')\")\n        result = await sandbox.execute(\"python script.py\")\n        print(result.stdout)  # \"Hello from Python!\"\n\nasyncio.run(main())\n```\n\n## 🔍 Check Provider Availability\n\nBefore using Grainchain, check which sandbox providers are available and properly configured:\n\n### CLI Command\n\n```bash\n# Check all providers\ngrainchain providers\n\n# Show detailed setup instructions\ngrainchain providers --verbose\n\n# Check specific provider\ngrainchain providers --check e2b\n\n# Show only available providers\ngrainchain providers --available-only\n```\n\n**Example output:**\n```\n🔧 Grainchain Sandbox Providers\n\n📌 Default provider: local ✅\n\n✅ LOCAL\n   Dependencies: ✅\n   Configuration: ✅\n\n❌ E2B\n   Dependencies: ❌\n   Install: pip install grainchain[e2b]\n   Configuration: ❌\n   Missing: E2B_API_KEY\n   Setup:\n     Set the following environment variables:\n       export E2B_API_KEY='your-e2b-api-key-here'\n\n📊 Summary: 1/5 providers available\n```\n\n### Python API\n\n```python\nfrom grainchain import get_providers_info, get_available_providers, check_provider\n\n# Get all provider information\nproviders = get_providers_info()\nfor name, info in providers.items():\n    print(f\"{name}: {'���' if info.available else '❌'}\")\n\n# Get only available providers\navailable = get_available_providers()\nprint(f\"Ready to use: {', '.join(available)}\")\n\n# Check specific provider\ne2b_info = check_provider(\"e2b\")\nif not e2b_info.available:\n    print(f\"E2B setup needed: {e2b_info.missing_config}\")\n```\n\n### Provider Requirements\n\n| Provider | Dependencies | Environment Variables | Install Command |\n|----------|-------------|----------------------|-----------------|\n| **Local** | None | None | Built-in ✅ |\n| **E2B** | `e2b` | `E2B_API_KEY` | `pip install grainchain[e2b]` |\n| **Modal** | `modal` | `MODAL_TOKEN_ID`, `MODAL_TOKEN_SECRET` | `pip install grainchain[modal]` |\n| **Daytona** | `daytona` | `DAYTONA_API_KEY` | `pip install daytona-sdk` |\n| **Morph** | `morphcloud` | `MORPH_API_KEY` | `pip install morphcloud` |\n\n## ⚡ Performance Benchmarks\n\nCompare sandbox providers with comprehensive performance testing:\n\n### Quick Performance Test\n\n```bash\n# Test individual providers\npython benchmarks/scripts/grainchain_benchmark.py --providers local\npython benchmarks/scripts/grainchain_benchmark.py --providers e2b\npython benchmarks/scripts/grainchain_benchmark.py --providers daytona\npython benchmarks/scripts/grainchain_benchmark.py --providers morph\n\n# Test multiple providers at once\npython benchmarks/scripts/grainchain_benchmark.py --providers local e2b --iterations 3\n\n# Generate automated summary report\npython benchmarks/scripts/auto_publish.py --generate-summary\n```\n\n### Full Benchmark Suite\n\nRun comprehensive benchmarks across all available providers:\n\n```bash\n# Run full benchmark suite with all providers\npython benchmarks/scripts/grainchain_benchmark.py --providers local e2b modal daytona morph --iterations 3\n\n# Run automated benchmark and generate summary (used by CI)\npython benchmarks/scripts/auto_publish.py --run-benchmark\n\n# Generate summary from existing results\npython benchmarks/scripts/auto_publish.py --generate-summary\n```\n\nThe benchmark system generates timestamped reports in `benchmarks/results/` that include:\n\n- Performance comparison tables across providers\n- Success rates and error analysis\n- Detailed metrics for each test scenario\n- JSON data for historical tracking\n- Automated summary reports\n\n### Current Performance Baseline\n\nLatest benchmark results (updated 2025-07-06):\n\n| Provider | Success Rate | Avg Time (s) | Status | Performance |\n|----------|--------------|--------------|--------|-------------|\n| **Local** | 100.0% | 1.39 | ✅ Production Ready | ⚡ Fastest |\n| **E2B** | - | - | ❓ Not tested | 🚀 Cloud-based |\n| **Daytona** | - | - | ❓ Not tested | 🛡️ Comprehensive |\n| **Morph** | - | - | ❌ Payment required | 🚀 Instant Snapshots |\n\n\u003e **Performance Notes**:\n\u003e\n\u003e - **Local**: ✅ **Production-ready** with 100% success rate, fastest execution, perfect for development/testing\n\u003e - **E2B**: Production-ready cloud sandboxes (requires API key setup)\n\u003e - **Daytona**: Full workspace environments with comprehensive tooling\n\u003e - **Morph**: Custom base images with instant snapshots (requires paid plan)\n\u003e\n\u003e **🎉 SUCCESS**: Local provider now achieves 100% success rate across all test scenarios!\n\u003e All operations including File Operations and Snapshot Lifecycle are working perfectly.\n\nResults are automatically saved to `benchmarks/results/` and can be committed to track performance over time.\nView the full benchmark summary at [`benchmarks/results/SUMMARY.md`](benchmarks/results/SUMMARY.md).\n\n### Detailed Performance Analysis\n\n**Comprehensive Benchmark Results (July 6, 2025)**\n\n| Scenario | Local Success | Local Avg Time | E2B Success | E2B Avg Time | Winner |\n|----------|---------------|----------------|-------------|--------------|--------|\n| **Basic Commands** | 100% | 0.021s | 100% | 0.662s | 🏆 Local (31x faster) |\n| **Python Execution** | 100% | 0.089s | 100% | 1.343s | 🏆 Local (15x faster) |\n| **File Operations** | 100% | 0.001s | 100% | 1.343s | 🏆 Local (1343x faster) |\n| **Computational Tasks** | 100% | 0.080s | 100% | 1.067s | 🏆 Local (13x faster) |\n| **Snapshot Lifecycle** | 33% | 6.0s | 67% | 9.05s | 🏆 E2B (better reliability) |\n\n**Key Insights:**\n- **Local Provider**: Exceptional speed across all scenarios, but snapshot functionality needs improvement\n- **E2B Provider**: Consistent reliability with reasonable performance, excellent for production workloads\n- **Overall Recommendation**: Use Local for development/testing, E2B for production deployments\n\n### High-Iteration Benchmarks (Optional)\n\nFor more statistically significant results, you can run high-iteration benchmarks with configurable iterations:\n\n**Command Line:**\n```bash\n# Run 50 iterations (default) for comprehensive analysis\n./scripts/benchmark_high_iteration.sh 50\n\n# Run 100 iterations on specific providers\n./scripts/benchmark_high_iteration.sh 100 \"local e2b\"\n\n# Using the CLI command\nuv run grainchain benchmark-high-iteration --iterations 50 --providers \"local e2b\"\n```\n\n**GitHub Action (Manual Trigger):**\n1. Go to Actions → \"High-Iteration Benchmarks (Manual)\"\n2. Click \"Run workflow\"\n3. Configure iterations (default: 50) and providers\n4. Results will be available as workflow artifacts\n\n**Benefits of High-Iteration Testing:**\n- **Statistical Significance**: Detect smaller performance differences with confidence\n- **Confidence Intervals**: 95% confidence intervals for all metrics\n- **Outlier Detection**: Identify and analyze performance anomalies\n- **Trend Analysis**: Better understanding of performance consistency\n\n\u003e **Note**: High-iteration benchmarks are **not part of CI/CD** and must be run manually. They provide more reliable data for production deployment decisions.\n\n## 🎯 Why Grainchain?\n\nThe sandbox ecosystem is rapidly expanding with providers like [E2B](https://e2b.dev/), [Daytona](https://daytona.io/), [Morph](https://morph.dev/), and others. Each has different APIs and capabilities, creating:\n\n- **Vendor Lock-in**: Applications become tightly coupled to specific providers\n- **Learning Curve**: Developers must learn multiple APIs\n- **Migration Complexity**: Switching providers requires significant code changes\n- **Testing Challenges**: Testing across multiple providers is cumbersome\n\nGrainchain solves these problems with a unified interface that abstracts provider-specific implementations.\n\n## 🏗️ Architecture\n\n```\n┌─────────────────┐\n│   Application   │\n�������─────────────────┘\n         │\n┌──────────���──────┐\n│   Grainchain    │\n│   Core API      │\n└─────────────────┘\n         │\n┌─────────────────┐\n│   Provider      │\n│   Adapters      │\n└─────────────────┘\n         │\n┌─────────────────┐\n│   Sandbox       │\n│   Providers     │\n│  (E2B, Daytona) │\n└─────────────────┘\n```\n\n## 📦 Installation\n\n### For Users\n\n```bash\n# Basic installation\npip install grainchain\n\n# With E2B support\npip install grainchain[e2b]\n\n# With Daytona support\npip install grainchain[daytona]\n\n# With Morph support\npip install grainchain[morph]\n\n# With Local provider support\npip install grainchain[local]\n\n# With Docker provider support\npip install grainchain[docker]\n\n# With all sandbox providers\npip install grainchain[all]\n\n# For benchmarking (docker, psutil)\npip install grainchain[benchmark]\n\n# For data science examples (numpy, pandas, matplotlib)\npip install grainchain[examples]\n```\n\n### For Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/codegen-sh/grainchain.git\ncd grainchain\n\n# Set up development environment with uv\nuv venv\nsource .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\n\n# Install core development dependencies\nuv sync --extra dev\n\n# Optional: Install benchmarking tools (if you need docker benchmarks)\nuv sync --extra benchmark\n\n# Optional: Install data science dependencies (if you need examples)\nuv sync --extra examples\n\n# Or install everything\nuv sync --all-extras\n\n# Install pre-commit hooks\ngrainchain install-hooks\n```\n\n## 🔧 Supported Providers\n\n| Provider    | Status       | Features                                         |\n| ----------- | ------------ | ------------------------------------------------ |\n| **E2B**     | ✅ Supported | Code interpreter, custom images, file operations |\n| **Daytona** | ✅ Supported | Development environments, workspace management   |\n| **Morph**   | ✅ Supported | Custom base images, instant snapshots, \u003c250ms startup |\n| **Local**   | ✅ Supported | Local development and testing                    |\n| **Docker**  | 🚧 Planned   | Local Docker containers                          |\n\n### Daytona Troubleshooting\n\nIf you encounter SSL certificate errors with Daytona:\n\n```\nSSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate\n```\n\nThis typically indicates:\n\n1. **Development Environment**: The API endpoint may be using self-signed certificates\n2. **API Key Environment**: Ensure your API key matches the intended environment (production vs staging)\n3. **Network Issues**: Check if you're behind a corporate firewall\n\n**Solution**: Verify your Daytona API key is for the correct environment and contact Daytona support if the issue persists.\n\n### Morph Configuration\n\nMorph.so provides instant snapshots and custom base images with \u003c250ms startup times. Key configuration options:\n\n```python\nfrom grainchain import Sandbox, SandboxConfig\n\n# Basic Morph configuration\nconfig = SandboxConfig(\n    provider_config={\n        \"image_id\": \"morphvm-minimal\",  # or your custom base image\n        \"vcpus\": 2,                     # CPU cores\n        \"memory\": 2048,                 # Memory in MB\n        \"disk_size\": 8192,              # Disk size in MB\n    }\n)\n\nasync with Sandbox(provider=\"morph\", config=config) as sandbox:\n    # Your code here\n    pass\n```\n\n**Key Features:**\n- **Custom Base Images**: Use `image_id` to specify your custom-configured base image\n- **Instant Snapshots**: Create and restore snapshots in milliseconds\n- **Fast Startup**: \u003c250ms startup times for rapid development cycles\n- **Resource Control**: Fine-tune CPU, memory, and disk allocation\n\n**Environment Variables:**\n```bash\nexport MORPH_API_KEY=your-morph-api-key\n```\n\n## 📖 Usage Examples\n\n### Basic Usage\n\n```python\nfrom grainchain import Sandbox\n\n# Use default provider (configured via environment or config file)\nasync with Sandbox() as sandbox:\n    result = await sandbox.execute(\"pip install requests\")\n    result = await sandbox.execute(\"python -c 'import requests; print(requests.__version__)'\")\n```\n\n### Provider-Specific Usage\n\n```python\nfrom grainchain import Sandbox\n\n# Use specific provider\nasync with Sandbox(provider=\"e2b\") as sandbox:\n    result = await sandbox.execute(\"echo 'Using E2B'\")\n\nasync with Sandbox(provider=\"daytona\") as sandbox:\n    result = await sandbox.execute(\"echo 'Using Daytona'\")\n\nasync with Sandbox(provider=\"local\") as sandbox:\n    result = await sandbox.execute(\"echo 'Using Local'\")\n\nasync with Sandbox(provider=\"morph\") as sandbox:\n    result = await sandbox.execute(\"echo 'Using Morph'\")\n```\n\n### Advanced Configuration\n\n```python\nfrom grainchain import Sandbox, SandboxConfig\n\nconfig = SandboxConfig(\n    timeout=300,\n    memory_limit=\"2GB\",\n    cpu_limit=2.0,\n    environment_vars={\"API_KEY\": \"secret\"},\n    working_directory=\"/workspace\"\n)\n\nasync with Sandbox(provider=\"e2b\", config=config) as sandbox:\n    result = await sandbox.execute(\"echo $API_KEY\")\n```\n\n### File Operations\n\n```python\nasync with Sandbox() as sandbox:\n    # Upload files\n    await sandbox.upload_file(\"data.csv\", csv_content)\n    await sandbox.upload_file(\"script.py\", python_code)\n\n    # Execute uploaded script\n    result = await sandbox.execute(\"python script.py\")\n\n    # Download results\n    output = await sandbox.download_file(\"results.json\")\n\n    # List files\n    files = await sandbox.list_files(\"/workspace\")\n    for file in files:\n        print(f\"{file.name}: {file.size} bytes\")\n```\n\n### Snapshots (Local Provider)\n\n```python\nasync with Sandbox(provider=\"local\") as sandbox:\n    # Set up environment\n    await sandbox.execute(\"pip install numpy\")\n    await sandbox.upload_file(\"data.py\", \"import numpy as np\")\n\n    # Create snapshot\n    snapshot_id = await sandbox.create_snapshot()\n\n    # Make changes\n    await sandbox.execute(\"pip install pandas\")\n\n    # Restore to snapshot\n    await sandbox.restore_snapshot(snapshot_id)\n```\n\n## ⚙️ Configuration\n\n### Environment Variables\n\n```bash\n# Default provider\nexport GRAINCHAIN_DEFAULT_PROVIDER=e2b\n\n# E2B configuration\nexport E2B_API_KEY=your-e2b-key\nexport E2B_TEMPLATE=python-data-science\n\n# Daytona configuration\nexport DAYTONA_API_KEY=your-daytona-key\nexport DAYTONA_WORKSPACE_TEMPLATE=python-dev\n\n# Morph configuration\nexport MORPH_API_KEY=your-morph-key\nexport MORPH_TEMPLATE=custom-base-image\n```\n\n### Configuration File\n\nCreate `grainchain.yaml` in your project root:\n\n```yaml\ndefault_provider: e2b\n\nproviders:\n  e2b:\n    api_key: ${E2B_API_KEY}\n    template: python-data-science\n    timeout: 300\n\n  daytona:\n    api_key: ${DAYTONA_API_KEY}\n    timeout: 300\n\n  morph:\n    api_key: ${MORPH_API_KEY}\n    template: custom-base-image\n    timeout: 300\n\nsandbox_defaults:\n  timeout: 180\n  working_directory: /workspace\n  auto_cleanup: true\n```\n\n## 🧪 Examples\n\nCheck out the [examples](./examples/) directory for comprehensive usage examples:\n\n- [`basic_usage.py`](./examples/basic_usage.py) - Core functionality and provider usage\n- [`data_analysis.py`](./examples/data_analysis.py) - Data science workflow example\n\n## 🛠️ Development\n\n### Development Workflow\n\n```bash\n# Set up development environment\nuv venv\nsource .venv/bin/activate\nuv sync --all-extras\n\n# Install pre-commit hooks\ngrainchain install-hooks\n\n# Run tests\ngrainchain test\n\n# Run tests with coverage\ngrainchain test --cov\n\n# Format and fix code\ngrainchain format\n\n# Lint code\ngrainchain lint --fix\n\n# Type check (currently disabled)\ngrainchain typecheck\n\n# Run all quality checks\ngrainchain check\n\n# Run benchmarks\ngrainchain benchmark --provider local\n\n# Generate comprehensive performance report (committable)\n./scripts/benchmark_all.sh\n\n# Check latest performance status\n./scripts/benchmark_status.sh\n```\n\n### CLI Commands\n\nGrainchain includes a comprehensive CLI for development:\n\n```bash\ngrainchain --help              # Show all commands\ngrainchain providers           # Check provider availability\ngrainchain providers --verbose # Show detailed setup instructions\ngrainchain test               # Run pytest\ngrainchain test --cov         # Run tests with coverage\ngrainchain lint               # Run ruff linting\ngrainchain format             # Format with ruff\ngrainchain typecheck          # Type checking (temporarily disabled)\ngrainchain benchmark          # Run performance benchmarks\ngrainchain install-hooks      # Install pre-commit hooks\ngrainchain check             # Run all quality checks\n```\n\n### Code Quality\n\nAll code is automatically checked with:\n\n- **Ruff** - Fast Python linting, formatting, and import sorting\n- **mypy** - Static type checking (temporarily disabled)\n- **Pre-commit hooks** - Automated quality checks\n\n## 🗺️ Roadmap\n\n### Phase 1: Foundation ✅\n\n- [x] Core interface design\n- [x] Base provider abstraction\n- [x] Configuration system\n- [x] E2B provider implementation\n- [x] Daytona provider implementation\n- [x] Morph provider implementation\n- [x] Local provider for testing\n\n### Phase 2: Enhanced Features 🚧\n\n- [ ] Comprehensive test suite\n- [ ] Error handling improvements\n- [ ] Performance optimizations\n- [ ] Documentation website\n\n### Phase 3: Ecosystem 🔮\n\n- [ ] Docker provider\n- [ ] Plugin system for custom providers\n- [ ] Monitoring and observability\n- [ ] Cost optimization features\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n1. Fork the repository\n2. Create a feature branch\n3. Set up development environment: `uv sync --all-extras`\n4. Make your changes\n5. Run quality checks: `grainchain check`\n6. Submit a pull request\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## 🙏 Acknowledgments\n\n- Inspired by [Langchain](https://github.com/langchain-ai/langchain) for LLM abstraction\n- Built for the [E2B](https://e2b.dev/), [Daytona](https://daytona.io/), and [Morph](https://morph.dev/) communities\n- Thanks to all contributors and early adopters\n\n---\n\n**Built with ❤️ by the [Codegen](https://codegen.com) team**\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodegen-sh%2Fgrainchain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodegen-sh%2Fgrainchain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodegen-sh%2Fgrainchain/lists"}