deepagents-opensandbox 1.0.1__tar.gz

deepagents_opensandbox-1.0.1/.github/workflows/publish-to-pypi.yml

@@ -0,0 +1,73 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - '*'
+
+permissions:
+  contents: read
+
+jobs:
+  package-test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        run: python -m pip install uv
+
+      - name: Run tests
+        run: |
+          uv sync
+          uv run --group dev pytest
+
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Build release distributions
+        run: |
+          # NOTE: put your own distribution build steps here.
+          python -m pip install build
+          python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      id-token: write
+
+    environment:
+      name: pypi
+      url: https://pypi.org/p/opensandbox
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

deepagents_opensandbox-1.0.1/.gitignore

@@ -0,0 +1,112 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# dotenv
+.env
+
+# virtualenv
+.venv
+venv/
+ENV/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# this package
+.idea/
+.vscode/
+.cursor/
+.claude/
+.codex/
+.pytest_cache/
+.DS_Store
+*.pyc
+*.swp
+*.whl

deepagents_opensandbox-1.0.1/AGENTS.md

@@ -0,0 +1,70 @@
+# AGENTS.md
+
+## Project Overview
+`deepagents-opensandbox` is a Python package that implements a sandbox backend for the [DeepAgents](https://github.com/shkarupa-alex/deepagents) framework using [OpenSandbox](https://github.com/alibaba/OpenSandbox). It allows DeepAgents to execute code and commands in isolated OpenSandbox environments.
+
+- **Language**: Python 3.11+
+- **Dependency Manager**: `uv`
+
+## Project Structure
+
+```
+deepagents-opensandbox/
+├── deepagents_opensandbox/
+│   ├── __init__.py             # Package exports
+│   ├── backend.py              # OpensandboxBackend implementation
+│   ├── provider.py             # OpensandboxProvider implementation
+│   ├── conftest.py             # Shared test fixtures
+│   ├── backend_test.py         # Backend unit and integration tests
+│   └── provider_test.py        # Provider unit and integration tests
+├── pyproject.toml              # Project configuration and dependencies
+├── uv.lock                     # Dependency lock file
+├── docker-compose.yaml         # Local dev server (OpenSandbox in Docker)
+└── AGENTS.md                   # Documentation for AI coding agents
+```
+
+## Architecture
+
+### 1. `OpensandboxBackend` (`backend.py`)
+- Inherits from `BaseSandbox` from `deepagents.backends.sandbox`.
+- Wraps `SandboxSync` for execute/upload/download.
+- Command execution via `sandbox.commands.run()` + `sandbox.commands.get_command_status()`.
+- File upload via `sandbox.files.write_file()`, download via `sandbox.files.read_bytes()`.
+
+### 2. `OpensandboxProvider` (`provider.py`)
+- Inherits from `SandboxProvider` from `deepagents_cli.integrations.sandbox_provider`.
+- Lifecycle management: create, connect, delete (sync + async).
+- Async path (`aget_or_create`) uses native async SDK (`Sandbox`) for non-blocking creation, then wraps in sync `SandboxSync` backend.
+- Configuration via env vars: `OPEN_SANDBOX_API_KEY`, `OPEN_SANDBOX_DOMAIN`.
+
+## Commands
+
+- **Unit tests**: `uv run python -m pytest deepagents_opensandbox/ -v -k "not integration"`
+- **Integration tests**: `OPEN_SANDBOX_DOMAIN=localhost:8090 uv run python -m pytest deepagents_opensandbox/ -v -k integration`
+- **All tests**: `OPEN_SANDBOX_DOMAIN=localhost:8090 uv run python -m pytest deepagents_opensandbox/ -v`
+- **Lint**: `uv run ruff check deepagents_opensandbox/`
+- **Format check**: `uv run ruff format --check deepagents_opensandbox/`
+
+## Server proxy mode
+
+The SDK can talk to sandbox containers in two ways:
+
+1. **Direct** (`use_server_proxy=False`, default): SDK connects to container IP/port directly. Works when client and containers are on the same network.
+2. **Server proxy** (`use_server_proxy=True`): All execd requests go through the OpenSandbox server at `OPEN_SANDBOX_DOMAIN`. Required when the client cannot reach container IPs (e.g. server in Docker, client on host — `host.docker.internal` is not resolvable from macOS host).
+
+`use_server_proxy` defaults to `False` in `OpensandboxProvider`. Integration tests pass `True` explicitly because they run from the host against a Docker-based server. Our docker-compose setup runs the server in Docker with `host_ip = "host.docker.internal"`.
+
+## Known issues
+
+- **Server ≤ v0.1.4**: proxy handler in `lifecycle.py` drops query parameters on GET requests (builds `target_url` without `request.url.query`). File downloads via proxy return `400 MISSING_QUERY`. Fixed in `main` (not yet released). Workaround: build server image from source. Our docker-compose uses a locally-built image with this fix.
+
+## Development Standards
+
+### Code Style
+- **Formatter/Linter**: `ruff` (configuration in `pyproject.toml`).
+- **Type Hints**: Strict typing enforced.
+- **Docstrings**: Google-style for public APIs.
+
+### Testing
+- Tests are in `*_test.py` files alongside source code.
+- Integration tests are gated by `OPEN_SANDBOX_DOMAIN` env var and a TCP connectivity check (`integration_server_available()` in `conftest.py`).

deepagents_opensandbox-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shkarupa Alex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

deepagents_opensandbox-1.0.1/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: deepagents-opensandbox
+Version: 1.0.1
+Summary: Opensandbox backend for DeepAgents
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: deepagents>=0.4.5
+Requires-Dist: opensandbox>=0.1.5
+Provides-Extra: cli
+Requires-Dist: deepagents-cli>=0.0.27; extra == 'cli'
+Description-Content-Type: text/markdown
+
+# deepagents-opensandbox
+
+OpenSandbox backend for the [DeepAgents](https://github.com/shkarupa-alex/deepagents) framework. This package enables DeepAgents to launch and control isolated sandbox environments using [OpenSandbox](https://github.com/nicholasgriffintn/OpenSandbox).
+
+## Key Features
+
+- **Sandbox Provider**: Manages the lifecycle of OpenSandbox instances (create, connect, delete) via the `SandboxProvider` interface from `deepagents-cli`.
+- **Sandbox Backend**: Provides a standard interface for command execution and file operations within a sandbox using the synchronous OpenSandbox SDK (`SandboxSync`).
+- **DeepAgents Integration**: Fully compatible with `BaseSandbox` and `SandboxProvider` interfaces.
+
+## Installation
+
+```bash
+pip install deepagents-opensandbox
+```
+
+## Usage
+
+```python
+from deepagents_opensandbox import OpensandboxProvider
+
+# Initialize the provider (uses OPEN_SANDBOX_API_KEY and OPEN_SANDBOX_DOMAIN env vars)
+provider = OpensandboxProvider()
+
+# Create a new sandbox
+sandbox = provider.get_or_create(image="python:3.11")
+
+# Execute a command
+result = sandbox.execute("echo 'Hello World'")
+print(result.output)
+
+# Clean up
+provider.delete(sandbox_id=sandbox.id)
+```
+
+### Using the backend directly
+
+```python
+from opensandbox.sync.sandbox import SandboxSync
+from deepagents_opensandbox import OpensandboxBackend
+
+sandbox = SandboxSync.create("python:3.11")
+backend = OpensandboxBackend(sandbox=sandbox)
+
+result = backend.execute("python --version")
+print(result.output)
+
+sandbox.kill()
+sandbox.close()
+```
+
+## Configuration
+
+| Environment Variable      | Description                          | Default          |
+|---------------------------|--------------------------------------|------------------|
+| `OPEN_SANDBOX_API_KEY`    | API key for authentication           | *(none)*         |
+| `OPEN_SANDBOX_DOMAIN`     | OpenSandbox server domain            | `localhost:8080` |
+
+### Server proxy mode
+
+By default, the SDK connects directly to sandbox container IPs. This works when the client and sandbox containers share the same network (e.g. both on the host, or in the same Docker/Kubernetes network).
+
+When the OpenSandbox **server runs inside Docker** and the client runs on the **host machine**, container IPs (like `host.docker.internal`) are not reachable from the host. In this case, enable server proxy mode so that all execd requests are routed through the server:
+
+```python
+provider = OpensandboxProvider(use_server_proxy=True)
+```
+
+| Deployment                              | `use_server_proxy` |
+|-----------------------------------------|--------------------|
+| Server native on host, client on host   | `False` (default)  |
+| Server in Docker, client on host        | `True`             |
+| Server in Docker, client in same network| `False`            |
+| Kubernetes with proper networking       | `False`            |
+
+> **Note:** OpenSandbox server `v0.1.4` and earlier have a [bug](https://github.com/alibaba/OpenSandbox) where the proxy handler drops query parameters on GET requests, causing file downloads to fail with `400 MISSING_QUERY`. The fix is merged into `main` but not yet released. If you hit this issue, build the server image from source (`server/` directory).
+
+## Development
+
+This project uses `uv` for dependency management.
+
+### Prerequisites
+
+- [uv](https://github.com/astral-sh/uv) installed.
+- Python 3.11 or higher.
+
+### Setup
+
+Install dependencies:
+
+```bash
+uv sync
+```
+
+### Testing
+
+Tests are split into unit tests (mocked) and integration tests (requiring a real server).
+
+**Run Unit Tests (Mocked)**
+
+These tests mock the OpenSandbox SDK calls and do not require a running server.
+
+```bash
+uv run python -m pytest deepagents_opensandbox/ -v
+```
+
+**Run Integration Tests**
+
+These tests verify behavior against a real OpenSandbox server. They use `use_server_proxy=True` since the test runner is on the host while the server is in Docker.
+
+```bash
+OPEN_SANDBOX_DOMAIN=localhost:8090 uv run python -m pytest deepagents_opensandbox/ -v -k integration
+```
+
+### Linting
+
+```bash
+uv run ruff check deepagents_opensandbox/
+uv run ruff format --check deepagents_opensandbox/
+```

deepagents_opensandbox-1.0.1/README.md

@@ -0,0 +1,120 @@
+# deepagents-opensandbox
+
+OpenSandbox backend for the [DeepAgents](https://github.com/shkarupa-alex/deepagents) framework. This package enables DeepAgents to launch and control isolated sandbox environments using [OpenSandbox](https://github.com/nicholasgriffintn/OpenSandbox).
+
+## Key Features
+
+- **Sandbox Provider**: Manages the lifecycle of OpenSandbox instances (create, connect, delete) via the `SandboxProvider` interface from `deepagents-cli`.
+- **Sandbox Backend**: Provides a standard interface for command execution and file operations within a sandbox using the synchronous OpenSandbox SDK (`SandboxSync`).
+- **DeepAgents Integration**: Fully compatible with `BaseSandbox` and `SandboxProvider` interfaces.
+
+## Installation
+
+```bash
+pip install deepagents-opensandbox
+```
+
+## Usage
+
+```python
+from deepagents_opensandbox import OpensandboxProvider
+
+# Initialize the provider (uses OPEN_SANDBOX_API_KEY and OPEN_SANDBOX_DOMAIN env vars)
+provider = OpensandboxProvider()
+
+# Create a new sandbox
+sandbox = provider.get_or_create(image="python:3.11")
+
+# Execute a command
+result = sandbox.execute("echo 'Hello World'")
+print(result.output)
+
+# Clean up
+provider.delete(sandbox_id=sandbox.id)
+```
+
+### Using the backend directly
+
+```python
+from opensandbox.sync.sandbox import SandboxSync
+from deepagents_opensandbox import OpensandboxBackend
+
+sandbox = SandboxSync.create("python:3.11")
+backend = OpensandboxBackend(sandbox=sandbox)
+
+result = backend.execute("python --version")
+print(result.output)
+
+sandbox.kill()
+sandbox.close()
+```
+
+## Configuration
+
+| Environment Variable      | Description                          | Default          |
+|---------------------------|--------------------------------------|------------------|
+| `OPEN_SANDBOX_API_KEY`    | API key for authentication           | *(none)*         |
+| `OPEN_SANDBOX_DOMAIN`     | OpenSandbox server domain            | `localhost:8080` |
+
+### Server proxy mode
+
+By default, the SDK connects directly to sandbox container IPs. This works when the client and sandbox containers share the same network (e.g. both on the host, or in the same Docker/Kubernetes network).
+
+When the OpenSandbox **server runs inside Docker** and the client runs on the **host machine**, container IPs (like `host.docker.internal`) are not reachable from the host. In this case, enable server proxy mode so that all execd requests are routed through the server:
+
+```python
+provider = OpensandboxProvider(use_server_proxy=True)
+```
+
+| Deployment                              | `use_server_proxy` |
+|-----------------------------------------|--------------------|
+| Server native on host, client on host   | `False` (default)  |
+| Server in Docker, client on host        | `True`             |
+| Server in Docker, client in same network| `False`            |
+| Kubernetes with proper networking       | `False`            |
+
+> **Note:** OpenSandbox server `v0.1.4` and earlier have a [bug](https://github.com/alibaba/OpenSandbox) where the proxy handler drops query parameters on GET requests, causing file downloads to fail with `400 MISSING_QUERY`. The fix is merged into `main` but not yet released. If you hit this issue, build the server image from source (`server/` directory).
+
+## Development
+
+This project uses `uv` for dependency management.
+
+### Prerequisites
+
+- [uv](https://github.com/astral-sh/uv) installed.
+- Python 3.11 or higher.
+
+### Setup
+
+Install dependencies:
+
+```bash
+uv sync
+```
+
+### Testing
+
+Tests are split into unit tests (mocked) and integration tests (requiring a real server).
+
+**Run Unit Tests (Mocked)**
+
+These tests mock the OpenSandbox SDK calls and do not require a running server.
+
+```bash
+uv run python -m pytest deepagents_opensandbox/ -v
+```
+
+**Run Integration Tests**
+
+These tests verify behavior against a real OpenSandbox server. They use `use_server_proxy=True` since the test runner is on the host while the server is in Docker.
+
+```bash
+OPEN_SANDBOX_DOMAIN=localhost:8090 uv run python -m pytest deepagents_opensandbox/ -v -k integration
+```
+
+### Linting
+
+```bash
+uv run ruff check deepagents_opensandbox/
+uv run ruff format --check deepagents_opensandbox/
+```

deepagents_opensandbox-1.0.1/deepagents_opensandbox/__init__.py

@@ -0,0 +1,27 @@
+"""Opensandbox integration for DeepAgents.
+
+This package provides:
+- OpensandboxBackend: Sandbox backend for executing commands in OpenSandbox containers
+- OpensandboxProvider: Provider for managing OpenSandbox lifecycle (requires ``deepagents-cli``)
+
+Example usage:
+    ```python
+    from deepagents_opensandbox import OpensandboxProvider
+
+    provider = OpensandboxProvider()
+    sandbox = provider.get_or_create(image="python:3.11")
+    result = sandbox.execute("echo 'Hello'")
+    provider.delete(sandbox_id=sandbox.id)
+    ```
+"""
+
+from deepagents_opensandbox.backend import OpensandboxBackend
+
+__all__ = ["OpensandboxBackend"]
+
+try:
+    from deepagents_opensandbox.provider import OpensandboxProvider
+
+    __all__ += ["OpensandboxProvider"]  # type: ignore[assignment]
+except ImportError:
+    pass