langchain-islo 0.0.1__tar.gz

langchain_islo-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Lint and test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e . ruff pytest pytest-socket "langchain-tests>=1.1.6"
+      - name: Lint
+        run: |
+          ruff check langchain_islo tests
+          ruff format langchain_islo tests --diff
+      - name: Unit tests
+        run: pytest tests/unit_tests tests/test_import.py -q --disable-socket --allow-unix-socket

langchain_islo-0.0.1/.github/workflows/workflow.yml

@@ -0,0 +1,50 @@
+name: Release
+
+# Publishes langchain-islo to PyPI via Trusted Publishing (OIDC, no token).
+# Matches the PyPI pending publisher: repo islo-labs/langchain-islo,
+# workflow file workflow.yml, environment "pypi".
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Check metadata
+        run: |
+          python -m pip install --upgrade twine
+          python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

langchain_islo-0.0.1/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+dist/
+*.egg-info/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/

langchain_islo-0.0.1/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.0.1
+
+Initial release.
+
+- `IsloSandbox`: a `deepagents` `BaseSandbox` backend for [Islo](https://islo.dev),
+  implementing `execute()`, `upload_files()`, `download_files()`, and `id`.
+  Filesystem tools (`ls`, `read`, `write`, `edit`, `glob`, `grep`) are inherited
+  from `BaseSandbox`.
+- `IsloProvider`: optional lifecycle helper (`get_or_create()` / `delete()`).
+- Validated against the `deepagents` `SandboxIntegrationTests` standard suite.

langchain_islo-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Islo
+
+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.

langchain_islo-0.0.1/Makefile

@@ -0,0 +1,60 @@
+.PHONY: format lint type typecheck test tests integration_test integration_tests test_watch help lint_package
+
+.DEFAULT_GOAL := help
+
+.EXPORT_ALL_VARIABLES:
+UV_FROZEN = true
+
+######################
+# TESTING
+######################
+
+TEST_FILE ?= tests/unit_tests/
+PYTEST_EXTRA ?=
+
+integration_test integration_tests: TEST_FILE=tests/integration_tests/
+
+test: ## Run unit tests
+test tests:
+	uv run --group test pytest -vvv $(PYTEST_EXTRA) --disable-socket --allow-unix-socket $(TEST_FILE)
+
+integration_test: ## Run integration tests
+integration_test integration_tests:
+	uv run --group test pytest -vvv --timeout 120 $(TEST_FILE)
+
+test_watch: ## Run tests in watch mode
+	uv run --group test ptw --now . -- -vv $(TEST_FILE)
+
+######################
+# LINTING AND FORMATTING
+######################
+
+PYTHON_FILES=.
+lint format: PYTHON_FILES=.
+lint_package: ## Lint only the package
+lint_package: PYTHON_FILES=langchain_islo
+
+lint: ## Run linters and type checker
+lint lint_package:
+	[ "$(PYTHON_FILES)" = "" ] || uv run --all-groups ruff check $(PYTHON_FILES)
+	[ "$(PYTHON_FILES)" = "" ] || uv run --all-groups ruff format $(PYTHON_FILES) --diff
+	$(MAKE) type
+
+type: ## Run type checker
+type typecheck:
+	uv run --all-groups ty check langchain_islo
+
+format: ## Run code formatters
+format:
+	[ "$(PYTHON_FILES)" = "" ] || uv run --all-groups ruff format $(PYTHON_FILES)
+	[ "$(PYTHON_FILES)" = "" ] || uv run --all-groups ruff check --fix $(PYTHON_FILES)
+
+######################
+# HELP
+######################
+
+help: ## Show this help message
+	@echo "Usage: make [target] [TEST_FILE=path/to/tests/]"
+	@echo ""
+	@echo "Targets:"
+	@awk 'BEGIN {FS = ":.*##"} /^[a-zA-Z_-]+:.*##/ {printf "  %-20s %s\n", $$1, $$2}' $(MAKEFILE_LIST)

langchain_islo-0.0.1/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: langchain-islo
+Version: 0.0.1
+Summary: Islo (islo.dev) sandbox integration for Deep Agents
+Project-URL: Homepage, https://github.com/islo-labs/langchain-islo
+Project-URL: Repository, https://github.com/islo-labs/langchain-islo
+Project-URL: Documentation, https://docs.islo.dev
+Project-URL: Issue Tracker, https://github.com/islo-labs/langchain-islo/issues
+Author: Islo
+License: MIT
+License-File: LICENSE
+Keywords: agents,deepagents,islo,langchain,sandbox
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: <4.0,>=3.11
+Requires-Dist: deepagents<0.7.0,>=0.6.8
+Requires-Dist: httpx>=0.21.2
+Requires-Dist: islo>=0.3.3
+Description-Content-Type: text/markdown
+
+# langchain-islo
+
+[![PyPI - Version](https://img.shields.io/pypi/v/langchain-islo?label=%20)](https://pypi.org/project/langchain-islo/#history)
+[![PyPI - License](https://img.shields.io/pypi/l/langchain-islo)](https://opensource.org/licenses/MIT)
+
+[Islo](https://islo.dev) sandbox integration for [Deep Agents](https://github.com/langchain-ai/deepagents).
+
+Islo provides long-running, reconnect-surviving AI sandboxes on real Linux VMs,
+with pause/resume, snapshots, and a gateway layer for secret isolation and
+egress policies.
+
+## Install
+
+```bash
+pip install langchain-islo
+```
+
+Set your API key (keys look like `ak_...`):
+
+```bash
+export ISLO_API_KEY="ak_..."
+```
+
+## Usage
+
+Wrap an existing Islo sandbox and use it as a Deep Agents backend:
+
+```python
+from islo import Islo
+from langchain_islo import IsloSandbox
+
+client = Islo()  # reads ISLO_API_KEY
+sandbox = client.sandboxes.create_sandbox(image="ubuntu:24.04")
+
+backend = IsloSandbox(client=client, sandbox=sandbox)
+
+result = backend.execute("echo hello")
+print(result.output)  # "hello"
+
+# Filesystem tools are inherited from BaseSandbox:
+backend.write("/workspace/app.py", "print('hi')\n")
+print(backend.read("/workspace/app.py").file_data["content"])
+```
+
+### Lifecycle helper
+
+`IsloProvider` creates, attaches to, and deletes sandboxes for you:
+
+```python
+from langchain_islo import IsloProvider
+
+provider = IsloProvider()  # reads ISLO_API_KEY
+backend = provider.get_or_create(image="ubuntu:24.04")
+try:
+    print(backend.execute("uname -a").output)
+finally:
+    provider.delete(sandbox_id=backend.id)
+```
+
+## What you get
+
+`IsloSandbox` subclasses `deepagents.backends.sandbox.BaseSandbox`, so it
+implements the full `SandboxBackendProtocol`:
+
+| Method | Backed by |
+| --- | --- |
+| `execute()` | Islo `exec_in_sandbox` + result polling (commands run via `sh -c`) |
+| `upload_files()` / `download_files()` | Islo sandbox files endpoint (raw bytes) |
+| `ls` / `read` / `write` / `edit` / `glob` / `grep` | Inherited from `BaseSandbox` |
+| `id` | Islo sandbox id |
+
+Async variants (`aexecute`, `aupload_files`, `adownload_files`, ...) are provided
+by the base class via thread offloading.
+
+## Configuration
+
+| Env var | Default | Purpose |
+| --- | --- | --- |
+| `ISLO_API_KEY` | — | Bearer token used to authenticate |
+| `ISLO_BASE_URL` | `https://api.islo.dev` | Control-plane base URL |
+
+## License
+
+MIT

langchain_islo-0.0.1/README.md

@@ -0,0 +1,84 @@
+# langchain-islo
+
+[![PyPI - Version](https://img.shields.io/pypi/v/langchain-islo?label=%20)](https://pypi.org/project/langchain-islo/#history)
+[![PyPI - License](https://img.shields.io/pypi/l/langchain-islo)](https://opensource.org/licenses/MIT)
+
+[Islo](https://islo.dev) sandbox integration for [Deep Agents](https://github.com/langchain-ai/deepagents).
+
+Islo provides long-running, reconnect-surviving AI sandboxes on real Linux VMs,
+with pause/resume, snapshots, and a gateway layer for secret isolation and
+egress policies.
+
+## Install
+
+```bash
+pip install langchain-islo
+```
+
+Set your API key (keys look like `ak_...`):
+
+```bash
+export ISLO_API_KEY="ak_..."
+```
+
+## Usage
+
+Wrap an existing Islo sandbox and use it as a Deep Agents backend:
+
+```python
+from islo import Islo
+from langchain_islo import IsloSandbox
+
+client = Islo()  # reads ISLO_API_KEY
+sandbox = client.sandboxes.create_sandbox(image="ubuntu:24.04")
+
+backend = IsloSandbox(client=client, sandbox=sandbox)
+
+result = backend.execute("echo hello")
+print(result.output)  # "hello"
+
+# Filesystem tools are inherited from BaseSandbox:
+backend.write("/workspace/app.py", "print('hi')\n")
+print(backend.read("/workspace/app.py").file_data["content"])
+```
+
+### Lifecycle helper
+
+`IsloProvider` creates, attaches to, and deletes sandboxes for you:
+
+```python
+from langchain_islo import IsloProvider
+
+provider = IsloProvider()  # reads ISLO_API_KEY
+backend = provider.get_or_create(image="ubuntu:24.04")
+try:
+    print(backend.execute("uname -a").output)
+finally:
+    provider.delete(sandbox_id=backend.id)
+```
+
+## What you get
+
+`IsloSandbox` subclasses `deepagents.backends.sandbox.BaseSandbox`, so it
+implements the full `SandboxBackendProtocol`:
+
+| Method | Backed by |
+| --- | --- |
+| `execute()` | Islo `exec_in_sandbox` + result polling (commands run via `sh -c`) |
+| `upload_files()` / `download_files()` | Islo sandbox files endpoint (raw bytes) |
+| `ls` / `read` / `write` / `edit` / `glob` / `grep` | Inherited from `BaseSandbox` |
+| `id` | Islo sandbox id |
+
+Async variants (`aexecute`, `aupload_files`, `adownload_files`, ...) are provided
+by the base class via thread offloading.
+
+## Configuration
+
+| Env var | Default | Purpose |
+| --- | --- | --- |
+| `ISLO_API_KEY` | — | Bearer token used to authenticate |
+| `ISLO_BASE_URL` | `https://api.islo.dev` | Control-plane base URL |
+
+## License
+
+MIT

langchain_islo-0.0.1/docs/DOCS_PR.md

@@ -0,0 +1,50 @@
+# Docs PR to `langchain-ai/docs`
+
+> Do this **after** `langchain-islo` is published to PyPI. The maintainers
+> (issue #3777) only accept docs PRs for *already-published* sandbox packages.
+
+## 1. Add the integration page
+
+Copy [`islo.mdx`](./islo.mdx) to:
+
+```
+src/oss/python/integrations/sandboxes/islo.mdx
+```
+
+This mirrors the structure of the existing `daytona.mdx` / `modal.mdx` /
+`runloop.mdx` pages (Installation → Create a sandbox backend → Use with Deep
+Agents → Cleanup).
+
+## 2. Register it in the index
+
+In `src/oss/python/integrations/sandboxes/index.mdx`, add an Islo card to the
+grid (alphabetical-ish, alongside the others):
+
+```mdx
+<a href="/oss/integrations/sandboxes/islo" className="flex items-center justify-center gap-1.5 p-2 rounded-lg border border-gray-200 dark:border-gray-700 hover:border-gray-300 dark:hover:border-gray-600 no-underline">
+    <img className="block dark:hidden w-5 h-5" src="/images/providers/light/islo.svg" alt="" />
+    <img className="hidden dark:block w-5 h-5" src="/images/providers/dark/islo.svg" alt="" />
+    <span className="font-semibold">Islo</span>
+</a>
+```
+
+## 3. Add the provider logo
+
+Add light/dark SVGs (the index references both):
+
+```
+src/images/providers/light/islo.svg
+src/images/providers/dark/islo.svg
+```
+
+(Check `docs.json` / the nav config for whether the new page must also be listed
+in the sidebar navigation — grep for `daytona` to find every place it's
+referenced and add `islo` in the same spots.)
+
+## 4. Open the PR
+
+Title: `docs: add Islo sandbox integration`
+
+Body: link the published PyPI package (`https://pypi.org/project/langchain-islo/`)
+and the issue (`langchain-ai/deepagents#3777`), and note it follows the
+[sandbox contributing guide](https://docs.langchain.com/oss/python/contributing/implement-langchain#sandboxes).

langchain_islo-0.0.1/docs/PUBLISHING.md

@@ -0,0 +1,49 @@
+# Publishing `langchain-islo` to PyPI
+
+The maintainer's guidance on `langchain-ai/deepagents#3777` is: **ship as a
+standalone PyPI package**, then open a docs PR. This is the publish half.
+
+## Preconditions
+
+- [ ] Repo created (suggested: `islo-labs/langchain-islo`) with this package at root.
+- [ ] PyPI account + project owned by the Islo/Incredibuild org.
+- [ ] CI green: `make lint` and `make test` (unit tests run offline).
+
+## Build & check
+
+```bash
+uv build                      # or: python -m build
+uvx twine check dist/*
+```
+
+## Test it from a clean env (optional but recommended)
+
+```bash
+python -m venv /tmp/islo-check && . /tmp/islo-check/bin/activate
+pip install dist/langchain_islo-*.whl
+python -c "from langchain_islo import IsloSandbox, IsloProvider; print('ok')"
+```
+
+## Publish
+
+Trusted publishing (recommended) via GitHub Actions, or manually:
+
+```bash
+uvx twine upload dist/*
+```
+
+## Live integration test (needs a real account)
+
+```bash
+export ISLO_API_KEY="ak_..."
+make integration_test
+```
+
+This runs the deepagents standard suite (`SandboxIntegrationTests`) against a
+real Islo sandbox.
+
+## After publishing
+
+1. Confirm `pip install langchain-islo` works from PyPI.
+2. Open the docs PR — see [`DOCS_PR.md`](./DOCS_PR.md).
+3. Post the follow-up on issue #3777 — see [`issue-reply.md`](./issue-reply.md).

langchain_islo-0.0.1/docs/islo.mdx

@@ -0,0 +1,81 @@
+---
+title: "IsloSandbox integration"
+description: "Integrate with the IsloSandbox sandbox backend using LangChain Python."
+---
+
+[Islo](https://islo.dev) provides long-running, reconnect-surviving sandboxes on real Linux VMs, with pause/resume, snapshots, and a gateway layer for secret isolation and egress policies. See the [Islo docs](https://docs.islo.dev) for signup, authentication, and platform details.
+
+## Installation
+
+<CodeGroup>
+```bash pip
+pip install langchain-islo
+```
+
+```bash uv
+uv add langchain-islo
+```
+</CodeGroup>
+
+Set your API key (keys look like `ak_...`):
+
+```bash
+export ISLO_API_KEY="ak_..."
+```
+
+## Create a sandbox backend
+
+In Python, you create the sandbox using the provider SDK, then wrap it with the [deepagents backend](/oss/deepagents/backends).
+
+```python
+from islo import Islo
+
+from langchain_islo import IsloSandbox
+
+client = Islo()  # reads ISLO_API_KEY
+sandbox = client.sandboxes.create_sandbox(image="ubuntu:24.04")
+backend = IsloSandbox(client=client, sandbox=sandbox)
+
+result = backend.execute("echo hello")
+print(result.output)
+```
+
+## Use with Deep Agents
+
+```python
+from islo import Islo
+from langchain_anthropic import ChatAnthropic
+
+from deepagents import create_deep_agent
+from langchain_islo import IsloSandbox
+
+client = Islo()
+sandbox = client.sandboxes.create_sandbox(image="ubuntu:24.04")
+backend = IsloSandbox(client=client, sandbox=sandbox)
+
+agent = create_deep_agent(
+    model=ChatAnthropic(model="claude-sonnet-4-20250514"),
+    system_prompt="You are a coding assistant with sandbox access.",
+    backend=backend,
+)
+
+result = agent.invoke(
+    {
+        "messages": [
+            {"role": "user", "content": "Create a hello world Python script and run it"}
+        ]
+    }
+)
+```
+
+## Cleanup
+
+You are responsible for managing the sandbox lifecycle via the Islo SDK.
+When you are done, pause, stop, or delete the sandbox:
+
+```python
+client.sandboxes.pause_sandbox(sandbox.name)   # resume later with resume_sandbox
+client.sandboxes.delete_sandbox(sandbox.name)   # permanently delete
+```
+
+See also: [Sandboxes](/oss/deepagents/sandboxes).

langchain_islo-0.0.1/docs/issue-reply.md

@@ -0,0 +1,36 @@
+# Draft reply for langchain-ai/deepagents#3777
+
+> Post this once the package is on PyPI and the docs PR is open. It (a) confirms
+> you followed their standalone-package guidance and (b) gives the feedback
+> `mdrxy` explicitly asked for on recommending community integrations.
+
+---
+
+Thanks @mdrxy — totally understand the maintenance/security rationale for not
+taking new sandboxes in-tree.
+
+We went the standalone route as suggested:
+
+- 📦 Published **`langchain-islo`** to PyPI: https://pypi.org/project/langchain-islo/
+- It subclasses `BaseSandbox` and implements `execute()` / `upload_files()` /
+  `download_files()` / `id`, and passes the `SandboxIntegrationTests` standard
+  suite (`tests/integration_tests/test_sandbox.py`), per the
+  [contributing guide](https://docs.langchain.com/oss/python/contributing/implement-langchain#sandboxes).
+- 📄 Docs PR adding the integration page: <link to langchain-ai/docs PR>
+
+On your open question about how to surface community integration packages — a
+few ideas from the implementer's seat:
+
+1. **A "Community" section on the Sandboxes index page** (separate from the
+   first-party cards) that links out to third-party PyPI packages + their docs.
+   Zero maintenance for you, discoverable for users.
+2. **An optional entry-point / plugin hook** so `deepagents-cli --sandbox <name>`
+   can discover installed third-party backends without a hardcoded `choices`
+   list in `sandbox_factory.py`. Today adding a CLI sandbox name requires an
+   in-tree edit, which is the one thing a standalone package *can't* do — an
+   entry-point group (e.g. `deepagents.sandboxes`) would close that gap.
+3. **A lightweight "verified" badge** keyed off the standard test suite passing
+   in the package's own CI, so users can tell which community packages meet the
+   contract.
+
+Happy to prototype (1) or (2) as a PR if useful.

langchain_islo-0.0.1/langchain_islo/__init__.py

@@ -0,0 +1,6 @@
+"""Islo sandbox integration for Deep Agents."""
+
+from langchain_islo.provider import IsloProvider
+from langchain_islo.sandbox import IsloSandbox
+
+__all__ = ["IsloProvider", "IsloSandbox"]

langchain_islo-0.0.1/langchain_islo/_version.py

@@ -0,0 +1,5 @@
+"""Version information for `langchain-islo`."""
+
+# Keep the `x-release-please-version` annotation — release-please uses it to
+# bump `__version__` in sync with `pyproject.toml` on every release PR.
+__version__ = "0.0.1"  # x-release-please-version

langchain_islo-0.0.1/langchain_islo/provider.py

@@ -0,0 +1,92 @@
+"""Lifecycle provider for Islo sandboxes.
+
+[`IsloProvider`][langchain_islo.provider.IsloProvider] is an optional
+convenience that creates, attaches to, and deletes Islo sandboxes and returns a
+ready-to-use [`IsloSandbox`][langchain_islo.sandbox.IsloSandbox]. It is
+duck-typed to the lifecycle shape deepagents expects of a sandbox provider
+(``get_or_create`` / ``delete``) without importing the CLI package, mirroring the
+``RunloopProvider`` pattern.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from islo import Islo
+
+from langchain_islo.sandbox import IsloSandbox
+
+_DEFAULT_IMAGE = "ubuntu:24.04"
+
+
+class IsloProvider:
+    """Create, attach to, and delete Islo sandboxes.
+
+    Example:
+        ```python
+        from langchain_islo import IsloProvider
+
+        provider = IsloProvider(api_key="ak_...")
+        backend = provider.get_or_create(image="ubuntu:24.04")
+        try:
+            print(backend.execute("uname -a").output)
+        finally:
+            provider.delete(sandbox_id=backend.id)
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        client: Islo | None = None,
+        api_key: str | None = None,
+        image: str = _DEFAULT_IMAGE,
+    ) -> None:
+        """Initialize the provider.
+
+        Args:
+            client: A pre-configured ``islo.Islo`` client. If omitted, one is
+                created (reading ``ISLO_API_KEY`` / ``ISLO_BASE_URL`` from the
+                environment, or ``api_key`` when provided).
+            api_key: API key used to construct a client when ``client`` is not
+                supplied.
+            image: Default container image used when creating new sandboxes.
+        """
+        if client is None:
+            client = Islo(api_key=api_key) if api_key else Islo()
+        self._client = client
+        self._default_image = image
+
+    def get_or_create(
+        self,
+        *,
+        sandbox_id: str | None = None,
+        **kwargs: Any,
+    ) -> IsloSandbox:
+        """Attach to an existing sandbox or create a new one.
+
+        Args:
+            sandbox_id: If provided, attach to the existing Islo sandbox with
+                this id instead of creating a new one.
+            kwargs: Forwarded to ``client.sandboxes.create_sandbox(...)`` when
+                creating (e.g. ``image``, ``vcpus``, ``memory_mb``, ``env``,
+                ``gateway_profile``, ``snapshot_name``).
+
+        Returns:
+            A ready-to-use ``IsloSandbox``.
+        """
+        if sandbox_id is not None:
+            sandbox = self._client.sandboxes.get_sandbox_by_id(sandbox_id)
+        else:
+            kwargs.setdefault("image", self._default_image)
+            sandbox = self._client.sandboxes.create_sandbox(**kwargs)
+        return IsloSandbox(client=self._client, sandbox=sandbox)
+
+    def delete(self, *, sandbox_id: str, **_kwargs: Any) -> None:
+        """Delete an Islo sandbox by id.
+
+        Islo's delete API is keyed by sandbox *name*, so the id is resolved to a
+        name first.
+        """
+        sandbox = self._client.sandboxes.get_sandbox_by_id(sandbox_id)
+        self._client.sandboxes.delete_sandbox(sandbox.name)

langchain_islo-0.0.1/langchain_islo/sandbox.py

@@ -0,0 +1,298 @@
+"""Islo sandbox backend implementation.
+
+[`IsloSandbox`][langchain_islo.sandbox.IsloSandbox] wraps an Islo sandbox
+(https://islo.dev) and conforms to deepagents'
+[`SandboxBackendProtocol`][deepagents.backends.protocol.SandboxBackendProtocol].
+
+It subclasses [`BaseSandbox`][deepagents.backends.sandbox.BaseSandbox], so the
+filesystem tools (``ls``, ``read``, ``write``, ``edit``, ``glob``, ``grep``) are
+provided for free on top of three primitives implemented here:
+
+- ``execute`` -- run a shell command via Islo's exec API (submit + poll).
+- ``upload_files`` / ``download_files`` -- transfer raw bytes over Islo's
+  sandbox files endpoint.
+
+Notes:
+    The deepagents base class sends *full shell command strings* (pipes,
+    redirects, here-docs). Islo's ``exec_in_sandbox`` executes an ``argv`` list
+    directly without a shell, so every command is wrapped in
+    ``["/bin/sh", "-c", command]``.
+
+    Islo's generated ``upload_file`` / ``download_file`` SDK methods do not carry
+    file bytes, so byte transfer is performed against the sandbox files endpoint
+    on the *compute* base URL, reusing the client's resolved auth headers (the
+    same approach used by the Islo SDK's own ``islo.custom.files`` helpers).
+"""
+
+from __future__ import annotations
+
+import io
+import posixpath
+import shlex
+from typing import TYPE_CHECKING
+
+import httpx
+from deepagents.backends.protocol import (
+    FILE_NOT_FOUND,
+    INVALID_PATH,
+    IS_DIRECTORY,
+    PERMISSION_DENIED,
+    ExecuteResponse,
+    FileDownloadResponse,
+    FileOperationError,
+    FileUploadResponse,
+)
+from deepagents.backends.sandbox import BaseSandbox
+from islo.custom.exec import exec_and_wait_sync
+
+if TYPE_CHECKING:
+    from islo import Islo
+    from islo.types import SandboxResponse
+
+# Islo executes an argv list, not a shell line. deepagents emits shell command
+# strings (pipes, redirects, here-docs), so each command is run through `sh -c`.
+_SHELL: tuple[str, str] = ("/bin/sh", "-c")
+
+_TIMEOUT_EXIT_CODE = 124
+"""Exit code returned when a command exceeds its timeout (matches `timeout(1)`)."""
+
+_HTTP_NOT_FOUND = 404
+_HTTP_FORBIDDEN = 403
+_HTTP_BAD_REQUEST = 400
+
+
+class IsloSandbox(BaseSandbox):
+    """Islo sandbox backend conforming to ``SandboxBackendProtocol``.
+
+    Inherits all filesystem operations from ``BaseSandbox`` and implements
+    ``execute``, ``upload_files``, ``download_files``, and ``id`` using the Islo
+    Python SDK (https://github.com/islo-labs/python-sdk).
+
+    Example:
+        ```python
+        from islo import Islo
+        from langchain_islo import IsloSandbox
+
+        client = Islo()  # reads ISLO_API_KEY
+        sandbox = client.sandboxes.create_sandbox(image="ubuntu:24.04")
+        backend = IsloSandbox(client=client, sandbox=sandbox)
+
+        result = backend.execute("echo hello")
+        print(result.output)  # "hello"
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        client: Islo,
+        sandbox: SandboxResponse,
+        timeout: int = 30 * 60,
+        poll_interval: float = 0.5,
+        http_timeout: float = 60.0,
+    ) -> None:
+        """Wrap an existing Islo sandbox.
+
+        Args:
+            client: An authenticated ``islo.Islo`` client.
+            sandbox: An Islo ``SandboxResponse`` (e.g. from
+                ``client.sandboxes.create_sandbox(...)``). Sandbox operations are
+                keyed by ``sandbox.name``.
+            timeout: Default command timeout in seconds used by ``execute()``
+                when no explicit timeout is given. A value of ``0`` waits
+                indefinitely.
+            poll_interval: Seconds between polls of the exec result while waiting
+                for a command to finish.
+            http_timeout: Per-request timeout in seconds for file
+                upload/download transfers.
+        """
+        self._client = client
+        self._sandbox = sandbox
+        self._default_timeout = timeout
+        self._poll_interval = poll_interval
+        self._http_timeout = http_timeout
+
+    @property
+    def id(self) -> str:
+        """Return the Islo sandbox id."""
+        return self._sandbox.id
+
+    @property
+    def name(self) -> str:
+        """Return the Islo sandbox name (the key most Islo APIs use)."""
+        return self._sandbox.name
+
+    # -- command execution ---------------------------------------------------
+
+    def execute(
+        self,
+        command: str,
+        *,
+        timeout: int | None = None,
+    ) -> ExecuteResponse:
+        """Execute a shell command inside the sandbox.
+
+        Args:
+            command: Full shell command string to execute.
+            timeout: Maximum seconds to wait for completion. If ``None``, uses
+                the backend's default timeout. A value of ``0`` waits
+                indefinitely.
+
+        Returns:
+            ``ExecuteResponse`` with combined stdout/stderr, the exit code, and a
+            truncation flag.
+        """
+        effective_timeout = self._default_timeout if timeout is None else timeout
+        # The exec helper treats `timeout=None` as "poll indefinitely", which is
+        # the semantic deepagents assigns to a timeout of 0.
+        helper_timeout = None if effective_timeout == 0 else float(effective_timeout)
+
+        result = exec_and_wait_sync(
+            self._client,
+            self._sandbox.name,
+            [_SHELL[0], _SHELL[1], command],
+            timeout=helper_timeout,
+            poll_interval=self._poll_interval,
+        )
+
+        if result.timed_out:
+            return ExecuteResponse(
+                output=f"Command timed out after {effective_timeout} seconds",
+                exit_code=_TIMEOUT_EXIT_CODE,
+                truncated=False,
+            )
+
+        output = result.stdout
+        if result.stderr:
+            output = f"{output}{result.stderr}" if output else result.stderr
+
+        return ExecuteResponse(
+            output=output,
+            exit_code=result.exit_code,
+            truncated=False,
+        )
+
+    # -- file transfer -------------------------------------------------------
+
+    def upload_files(self, files: list[tuple[str, bytes]]) -> list[FileUploadResponse]:
+        """Upload files into the sandbox.
+
+        Supports partial success: per-file failures are returned as errors on the
+        corresponding ``FileUploadResponse`` rather than raised. Parent
+        directories are created before upload.
+        """
+        responses: list[FileUploadResponse | None] = []
+        pending: list[tuple[int, str, bytes]] = []
+
+        for path, content in files:
+            if not path.startswith("/"):
+                responses.append(FileUploadResponse(path=path, error=INVALID_PATH))
+                continue
+            responses.append(None)  # placeholder, filled after transfer
+            pending.append((len(responses) - 1, path, content))
+
+        if not pending:
+            return [r for r in responses if r is not None]
+
+        # Ensure parent directories exist (upload contract requirement).
+        parents = sorted(
+            {posixpath.dirname(p) for _, p, _ in pending if posixpath.dirname(p)}
+        )
+        if parents:
+            quoted = " ".join(shlex.quote(d) for d in parents)
+            self.execute(f"mkdir -p {quoted}")
+
+        base_url = self._compute_base_url()
+        headers = self._auth_headers()
+        with httpx.Client(timeout=self._http_timeout) as http:
+            for idx, path, content in pending:
+                filename = posixpath.basename(path) or "file"
+                try:
+                    response = http.post(
+                        f"{base_url}/sandboxes/{self._sandbox.name}/files",
+                        params={"path": path},
+                        headers=headers,
+                        files={"file": (filename, io.BytesIO(content))},
+                    )
+                    response.raise_for_status()
+                except httpx.HTTPStatusError as exc:
+                    responses[idx] = FileUploadResponse(
+                        path=path,
+                        error=_map_http_status(exc.response.status_code),
+                    )
+                except httpx.HTTPError as exc:  # network/timeout errors
+                    responses[idx] = FileUploadResponse(path=path, error=str(exc))
+                else:
+                    responses[idx] = FileUploadResponse(path=path, error=None)
+
+        return [r for r in responses if r is not None]
+
+    def download_files(self, paths: list[str]) -> list[FileDownloadResponse]:
+        """Download files from the sandbox.
+
+        Supports partial success: per-file failures are returned as errors on the
+        corresponding ``FileDownloadResponse`` rather than raised.
+        """
+        responses: list[FileDownloadResponse] = []
+        base_url = self._compute_base_url()
+        headers = self._auth_headers()
+
+        with httpx.Client(timeout=self._http_timeout) as http:
+            for path in paths:
+                if not path.startswith("/"):
+                    responses.append(
+                        FileDownloadResponse(
+                            path=path, content=None, error=INVALID_PATH
+                        )
+                    )
+                    continue
+                try:
+                    response = http.get(
+                        f"{base_url}/sandboxes/{self._sandbox.name}/files",
+                        params={"path": path},
+                        headers=headers,
+                    )
+                    response.raise_for_status()
+                except httpx.HTTPStatusError as exc:
+                    responses.append(
+                        FileDownloadResponse(
+                            path=path,
+                            content=None,
+                            error=_map_http_status(exc.response.status_code),
+                        )
+                    )
+                except httpx.HTTPError as exc:
+                    responses.append(
+                        FileDownloadResponse(path=path, content=None, error=str(exc))
+                    )
+                else:
+                    responses.append(
+                        FileDownloadResponse(
+                            path=path, content=response.content, error=None
+                        )
+                    )
+
+        return responses
+
+    # -- internals -----------------------------------------------------------
+
+    def _compute_base_url(self) -> str:
+        """Resolve the Islo *compute* base URL hosting the exec/files endpoints."""
+        return self._client._client_wrapper.get_environment().compute.rstrip("/")
+
+    def _auth_headers(self) -> dict[str, str]:
+        """Resolve fresh auth headers (honors token refresh) for raw requests."""
+        return self._client._client_wrapper.get_headers()
+
+
+def _map_http_status(status_code: int) -> FileOperationError | str:
+    """Map an HTTP status to a standardized ``FileOperationError`` literal."""
+    if status_code == _HTTP_NOT_FOUND:
+        return FILE_NOT_FOUND
+    if status_code == _HTTP_FORBIDDEN:
+        return PERMISSION_DENIED
+    if status_code == _HTTP_BAD_REQUEST:
+        return INVALID_PATH
+    if status_code == 409:  # noqa: PLR2004  # conflict: path is a directory
+        return IS_DIRECTORY
+    return f"http_{status_code}"

langchain_islo-0.0.1/pyproject.toml

@@ -0,0 +1,91 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langchain-islo"
+description = "Islo (islo.dev) sandbox integration for Deep Agents"
+license = { text = "MIT" }
+readme = "README.md"
+authors = [{ name = "Islo" }]
+keywords = ["deepagents", "langchain", "sandbox", "islo", "agents"]
+
+classifiers = [
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+version = "0.0.1"
+requires-python = ">=3.11,<4.0"
+dependencies = [
+    "deepagents>=0.6.8,<0.7.0",
+    "islo>=0.3.3",
+    "httpx>=0.21.2",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["langchain_islo"]
+
+[project.urls]
+Homepage = "https://github.com/islo-labs/langchain-islo"
+Repository = "https://github.com/islo-labs/langchain-islo"
+Documentation = "https://docs.islo.dev"
+"Issue Tracker" = "https://github.com/islo-labs/langchain-islo/issues"
+
+[dependency-groups]
+test = [
+    "pytest>=8.3.4,<10.0.0",
+    "pytest-cov",
+    "pytest-socket",
+    "pytest-xdist",
+    "pytest-timeout>=2.3.1,<3.0.0",
+    "pytest-asyncio>=1.3.0",
+    "ruff>=0.14.0,<1.0.0",
+    "ty>=0.0.1,<1.0.0",
+    "langchain-tests>=1.1.6",
+]
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "COM812",  # Messes with the formatter
+    "ISC001",  # Messes with the formatter
+    "ANN401",  # Dynamically typed expressions (typing.Any) — needed for **kwargs passthrough
+    "SLF001",  # Private member access — required to reuse the Islo client's resolved env/headers
+    "FBT001",  # Boolean positional arg — inherited signature shape from deepagents
+    "FBT002",  # Boolean default positional arg
+]
+extend-safe-fixes = ["PLR6201"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+ignore-var-parameters = true
+
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "all"
+
+[tool.ruff.lint.extend-per-file-ignores]
+"tests/**/*.py" = ["D", "S101", "SLF001", "PLR2004"]
+
+[tool.coverage.run]
+omit = ["tests/*"]
+
+[tool.pytest.ini_options]
+addopts = "--strict-markers --strict-config --durations=5"
+testpaths = ["tests"]
+markers = [
+    "requires: mark tests as requiring a specific library",
+    "compile: mark placeholder test used to compile integration tests without running them",
+    "scheduled: mark tests to run in scheduled testing",
+]
+asyncio_mode = "auto"
+filterwarnings = []

langchain_islo-0.0.1/tests/integration_tests/test_sandbox.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING
+
+import pytest
+from islo import Islo
+from langchain_tests.integration_tests import SandboxIntegrationTests
+
+from langchain_islo import IsloSandbox
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from deepagents.backends.protocol import SandboxBackendProtocol
+
+# Requires a live Islo account: set ISLO_API_KEY before running these.
+pytestmark = pytest.mark.skipif(
+    not os.environ.get("ISLO_API_KEY"),
+    reason="ISLO_API_KEY not set; skipping live Islo integration tests",
+)
+
+
+class TestIsloSandboxStandard(SandboxIntegrationTests):
+    @pytest.fixture
+    def sandbox(self) -> Iterator[SandboxBackendProtocol]:
+        client = Islo()
+        sandbox = client.sandboxes.create_sandbox(image="ubuntu:24.04")
+        backend = IsloSandbox(client=client, sandbox=sandbox)
+        try:
+            yield backend
+        finally:
+            client.sandboxes.delete_sandbox(sandbox.name)

langchain_islo-0.0.1/tests/test_import.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+import langchain_islo
+
+
+def test_import_islo() -> None:
+    assert langchain_islo is not None
+    assert hasattr(langchain_islo, "IsloSandbox")
+    assert hasattr(langchain_islo, "IsloProvider")

langchain_islo-0.0.1/tests/unit_tests/test_sandbox.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import httpx
+import pytest
+from islo.custom.exec import ExecResult
+
+from langchain_islo.sandbox import IsloSandbox, _map_http_status
+
+TIMEOUT_EXIT_CODE = 124
+
+
+def _make_sandbox() -> tuple[IsloSandbox, MagicMock]:
+    client = MagicMock()
+    client._client_wrapper.get_environment.return_value = SimpleNamespace(
+        compute="https://ca.compute.islo.dev",
+        control="https://api.islo.dev",
+    )
+    client._client_wrapper.get_headers.return_value = {
+        "Authorization": "Bearer ak_test"
+    }
+    sandbox = SimpleNamespace(id="sb-123", name="my-sandbox", status="running")
+    return IsloSandbox(client=client, sandbox=sandbox), client
+
+
+def test_id_and_name() -> None:
+    sb, _ = _make_sandbox()
+    assert sb.id == "sb-123"
+    assert sb.name == "my-sandbox"
+
+
+def test_execute_combines_stdout_and_stderr() -> None:
+    sb, _ = _make_sandbox()
+    with patch("langchain_islo.sandbox.exec_and_wait_sync") as mock_exec:
+        mock_exec.return_value = ExecResult(stdout="out", stderr="err", exit_code=0)
+        result = sb.execute("echo hi")
+
+    assert result.output == "outerr"
+    assert result.exit_code == 0
+    assert result.truncated is False
+
+    # Command must be wrapped in a shell so pipes/redirects/here-docs work.
+    args, _ = mock_exec.call_args
+    assert args[0] is sb._client
+    assert args[1] == "my-sandbox"
+    assert args[2] == ["/bin/sh", "-c", "echo hi"]
+
+
+def test_execute_stdout_only() -> None:
+    sb, _ = _make_sandbox()
+    with patch("langchain_islo.sandbox.exec_and_wait_sync") as mock_exec:
+        mock_exec.return_value = ExecResult(stdout="hello", stderr="", exit_code=0)
+        result = sb.execute("echo hello")
+    assert result.output == "hello"
+
+
+def test_execute_timeout_maps_to_124() -> None:
+    sb, _ = _make_sandbox()
+    with patch("langchain_islo.sandbox.exec_and_wait_sync") as mock_exec:
+        mock_exec.return_value = ExecResult(
+            stdout="", stderr="", exit_code=-1, timed_out=True
+        )
+        result = sb.execute("sleep 999", timeout=5)
+    assert result.exit_code == TIMEOUT_EXIT_CODE
+    assert "timed out" in result.output
+
+
+def test_execute_timeout_zero_means_wait_forever() -> None:
+    sb, _ = _make_sandbox()
+    with patch("langchain_islo.sandbox.exec_and_wait_sync") as mock_exec:
+        mock_exec.return_value = ExecResult(stdout="", stderr="", exit_code=0)
+        sb.execute("echo hi", timeout=0)
+    _, kwargs = mock_exec.call_args
+    assert kwargs["timeout"] is None
+
+
+def test_upload_rejects_relative_path() -> None:
+    sb, _ = _make_sandbox()
+    responses = sb.upload_files([("relative/path.txt", b"data")])
+    assert len(responses) == 1
+    assert responses[0].path == "relative/path.txt"
+    assert responses[0].error == "invalid_path"
+
+
+def test_upload_success_creates_parents_and_posts() -> None:
+    sb, _ = _make_sandbox()
+    http = MagicMock()
+    http.__enter__.return_value = http
+    response = MagicMock()
+    response.raise_for_status.return_value = None
+    http.post.return_value = response
+
+    with (
+        patch("langchain_islo.sandbox.httpx.Client", return_value=http),
+        patch.object(sb, "execute") as mock_execute,
+    ):
+        responses = sb.upload_files([("/workspace/app.py", b"print('hi')")])
+
+    assert responses[0].error is None
+    # mkdir -p for the parent directory should have been issued.
+    mkdir_cmd = mock_execute.call_args[0][0]
+    assert mkdir_cmd.startswith("mkdir -p ")
+    assert "/workspace" in mkdir_cmd
+    # The POST hits the compute files endpoint with the path param.
+    url = http.post.call_args[0][0]
+    assert url == "https://ca.compute.islo.dev/sandboxes/my-sandbox/files"
+    assert http.post.call_args[1]["params"] == {"path": "/workspace/app.py"}
+
+
+def test_upload_partial_success() -> None:
+    sb, _ = _make_sandbox()
+    http = MagicMock()
+    http.__enter__.return_value = http
+    ok = MagicMock()
+    ok.raise_for_status.return_value = None
+    bad_response = MagicMock(status_code=403)
+    err = httpx.HTTPStatusError("forbidden", request=MagicMock(), response=bad_response)
+    bad = MagicMock()
+    bad.raise_for_status.side_effect = err
+    http.post.side_effect = [ok, bad]
+
+    with (
+        patch("langchain_islo.sandbox.httpx.Client", return_value=http),
+        patch.object(sb, "execute"),
+    ):
+        responses = sb.upload_files([("/ok.txt", b"a"), ("/denied.txt", b"b")])
+
+    assert responses[0].error is None
+    assert responses[1].error == "permission_denied"
+
+
+def test_download_success_returns_bytes() -> None:
+    sb, _ = _make_sandbox()
+    http = MagicMock()
+    http.__enter__.return_value = http
+    response = MagicMock(content=b"file-bytes")
+    response.raise_for_status.return_value = None
+    http.get.return_value = response
+
+    with patch("langchain_islo.sandbox.httpx.Client", return_value=http):
+        responses = sb.download_files(["/workspace/app.py"])
+
+    assert responses[0].content == b"file-bytes"
+    assert responses[0].error is None
+
+
+def test_download_not_found() -> None:
+    sb, _ = _make_sandbox()
+    http = MagicMock()
+    http.__enter__.return_value = http
+    missing = MagicMock(status_code=404)
+    err = httpx.HTTPStatusError("nope", request=MagicMock(), response=missing)
+    response = MagicMock()
+    response.raise_for_status.side_effect = err
+    http.get.return_value = response
+
+    with patch("langchain_islo.sandbox.httpx.Client", return_value=http):
+        responses = sb.download_files(["/missing.txt"])
+
+    assert responses[0].content is None
+    assert responses[0].error == "file_not_found"
+
+
+def test_download_rejects_relative_path() -> None:
+    sb, _ = _make_sandbox()
+    responses = sb.download_files(["relative.txt"])
+    assert responses[0].error == "invalid_path"
+
+
+@pytest.mark.parametrize(
+    ("status", "expected"),
+    [
+        (404, "file_not_found"),
+        (403, "permission_denied"),
+        (400, "invalid_path"),
+        (409, "is_directory"),
+        (500, "http_500"),
+    ],
+)
+def test_map_http_status(status: int, expected: str) -> None:
+    assert _map_http_status(status) == expected