Proposal: OpenSandbox as an optional community SandboxProvider

[jianpingpei]

The ask

Would the team be open to an optional OpenSandbox-backed SandboxProvider for DeerFlow?

A tested prototype is available, but I would like to align on scope and packaging before opening a pull request.

Why

Teams that already use OpenSandbox cannot currently configure DeerFlow to reuse that sandbox control plane. They need to operate a separate DeerFlow-specific backend or maintain a private adapter.

The goal is to make OpenSandbox selectable through the existing sandbox.use mechanism without changing the default provider or the behavior of existing AIO, E2B, BoxLite, or Tenki users.

This proposal is related to the runtime evaluation discussed in #3213, but it has a narrower goal: provider/control-plane integration. It does not claim that running the same AIO image through OpenSandbox reduces per-sandbox memory, and it does not replace the ongoing AIO profiling work in that issue.

Proposed integration

The direct-provider form would be selected with configuration like:

sandbox:
  use: deerflow.community.opensandbox:OpenSandboxProvider
  image: python:3.11
  api_key: $OPEN_SANDBOX_API_KEY
  domain: sandbox.example.com
  protocol: https

The provider would:

• implement the complete DeerFlow Sandbox and SandboxProvider contracts;
• map command and native text/binary file operations to the OpenSandbox Python SDK;
• preserve per-user and per-thread isolation, active reuse, and warm-pool reclaim;
• support TTL renewal, command timeouts, idle cleanup, and terminal-session eviction;
• implement list_dir, glob, and grep with DeerFlow-compatible result semantics;
• enforce the existing /mnt/user-data download boundary and 100 MiB streaming download cap;
• remain opt-in behind an optional deerflow-harness[opensandbox] dependency.

No default behavior would change.

Alternatives considered

OpenSandbox as an AIO provisioning backend

This could reuse AioSandbox and its browser/Jupyter-oriented tool surface, but it requires broader changes for endpoint headers, remote thread-data and skill materialization, and AIO-specific lifecycle behavior.

External provider package

DeerFlow class-path loading already makes this technically possible. However, the existing E2B, BoxLite, and Tenki integrations suggest that an in-tree community provider may also be appropriate.

Prototype status

A current-main prototype is available here:

https://github.com/jianpingpei/deer-flow/tree/feat/opensandbox-provider-current-main

It includes the provider, optional dependency metadata, public configuration documentation, and focused unit tests. The focused provider/packaging suite, lint, lock validation, a full non-live backend test run, a live provider lifecycle flow, and a model-driven DeerFlow bash flow have been exercised. Deployment-specific endpoints, images, resource identifiers, and status payloads are intentionally omitted.

The current prototype deliberately treats capacity as a per-Gateway-process soft cap. Cross-process discovery and ownership coordination are not claimed in the first version.

Questions for maintainers

1. Would you prefer this as an in-tree deerflow.community.opensandbox provider or as an external package?
2. Is the direct SandboxProvider approach appropriate for a first version, or should OpenSandbox instead provision the DeerFlow AIO image?
3. Is command, file, search, and lifecycle parity sufficient for the first version, with browser/Jupyter parity treated separately?
4. Is a clearly documented single-Gateway ownership boundary acceptable initially, or is cross-process discovery required before contribution?

Happy to adapt the prototype to the preferred scope before opening a PR.