feat(integrations): Add OpenSandboxEnvironment for remote sandbox workspaces
- Dominant language
- Python
- Stars
- 21.5k
- Forks
- 4k
- Avg merge
- 1d 14h
- Merged PRs (30d)
- 37
Description
## 🔴 Required Information
### Is your feature request related to a specific problem?
Google ADK provides `BaseEnvironment` and `EnvironmentToolset` for persistent
workspace operations, and currently includes native remote environment
integrations for E2B and Daytona. OpenSandbox users cannot configure the
standard ADK environment tools with an OpenSandbox backend without maintaining
a custom `BaseEnvironment` adapter or replacing the standard toolset with
project-specific tools.
This makes it harder to use the same ADK agent against a locally hosted or
remotely hosted OpenSandbox deployment while preserving ADK's normal lifecycle,
command execution, and file-operation semantics.
### Describe the Solution You'd Like
Add an experimental `OpenSandboxEnvironment` integration under
`google.adk.integrations.opensandbox`:
```python
from google.adk.integrations.opensandbox import OpenSandboxEnvironment
from google.adk.tools.environment import EnvironmentToolset
toolset = EnvironmentToolset(
environment=OpenSandboxEnvironment(
image="python:3.11",
timeout=300,
)
)
```
The proposed adapter implements the existing `BaseEnvironment` contract and
does not require changes to that interface. Its initial scope is:
- create an owned sandbox or attach to a caller-owned sandbox;
- start from an image or snapshot;
- execute commands with working directory, environment variables, stdout,
stderr, exit code, and timeout mapping;
- read and write binary files and normalize missing files to
`FileNotFoundError`;
- renew the lifetime of owned sandboxes before operations;
- destroy owned sandboxes while leaving attached sandboxes running;
- keep the OpenSandbox SDK behind an optional `google-adk[opensandbox]` extra.
The integration would follow the public API, optional-dependency, feature flag,
sample, and unit-test structure already used by `E2BEnvironment` and
`DaytonaEnvironment`.
### Impact on your work
This would let teams use ADK's standard `EnvironmentToolset` with an
OpenSandbox deployment instead of maintaining a parallel tool implementation.
It also allows the sandbox runtime and deployment model to remain an
OpenSandbox concern while the agent code uses the same ADK environment API.
There is no hard external deadline. We would like maintainer feedback on the
integration shape before preparing an upstream pull request.
### Willingness to contribute
Yes. A working prototype is available at:
https://github.com/jianpingpei/adk-python/tree/feat/opensandbox-environment
The prototype currently has 28 focused unit tests and 60 passing related tests
covering OpenSandbox, E2B, Daytona, and `EnvironmentToolset`. It has also been
verified against a real local OpenSandbox Docker runtime and with a real
model-driven ADK agent calling `WriteFile`, `Execute`, and `ReadFile`. Any pull
request would be rebased onto the latest `main` and would include reproducible,
sanitized E2E commands and output.
---
## 🟡 Recommended Information
### Describe Alternatives You've Considered
1. **Keep the adapter outside ADK.** This works, but each user must discover,
install, and maintain a compatibility layer for an experimental ADK API.
2. **Expose custom OpenSandbox tools directly to the agent.** This bypasses
`EnvironmentToolset`, duplicates its tool behavior and instructions, and
makes switching environment backends harder.
3. **Use an existing hosted backend integration.** E2B and Daytona are useful
options, but they do not connect an ADK application to an existing
OpenSandbox deployment.
### Proposed API / Implementation
The implementation would be a small `BaseEnvironment` subclass plus:
- `google.adk.integrations.opensandbox` public export;
- an `opensandbox>=0.1.15,<0.2` optional extra;
- an experimental feature registry entry;
- focused unit tests using mocked SDK boundaries;
- an upstream-style sample using `EnvironmentToolset`;
- manual Runner/Agent E2E evidence using a real sandbox.
No new lifecycle abstraction or change to existing environment integrations is
proposed.
### Additional Context
- OpenSandbox project: https://github.com/opensandbox-group/OpenSandbox
- Existing E2B integration precedent: https://github.com/google/adk-python/pull/6031
Questions for maintainers:
1. Is `google.adk.integrations.opensandbox.OpenSandboxEnvironment` the desired
location and naming for this backend?
2. Should the first contribution include only the code integration and sample,
with user-facing documentation submitted separately to `google/adk-docs`?
Contributor guide
Assessment
This issue has not been assessed yet.