mirror of
https://github.com/bytedance/deer-flow.git
synced 2026-09-11 22:48:38 +00:00
76 lines
3.2 KiB
Markdown
76 lines
3.2 KiB
Markdown
# OpenSandbox backend
|
|
|
|
Runs DeerFlow sandboxes on [OpenSandbox](https://github.com/opensandbox-group/OpenSandbox),
|
|
using the synchronous Python SDK behind DeerFlow's `Sandbox` and
|
|
`SandboxProvider` contracts.
|
|
|
|
## Installation and configuration
|
|
|
|
Install the optional SDK, then select the provider:
|
|
|
|
```bash
|
|
pip install "deerflow-harness[opensandbox]"
|
|
```
|
|
|
|
```yaml
|
|
sandbox:
|
|
use: deerflow.community.opensandbox:OpenSandboxProvider
|
|
image: python:3.11
|
|
# api_key: $OPEN_SANDBOX_API_KEY
|
|
# domain: localhost:8080
|
|
# protocol: http
|
|
# request_timeout: 30
|
|
# ready_timeout: 30
|
|
# use_server_proxy: false
|
|
# sandbox_timeout: 14400 # remote lifetime; 0 means explicit cleanup only
|
|
# bash_command_timeout: 600 # default command timeout
|
|
# replicas: 3 # active + warm sandboxes per gateway process
|
|
# idle_timeout: 600 # warm seconds before destroy; 0 disables reaping
|
|
# environment:
|
|
# PYTHONUNBUFFERED: "1"
|
|
```
|
|
|
|
`api_key` and `domain` may be omitted when `OPEN_SANDBOX_API_KEY` and
|
|
`OPEN_SANDBOX_DOMAIN` are set. `use_server_proxy` is useful when DeerFlow can
|
|
reach the OpenSandbox management service but cannot directly reach sandbox
|
|
`execd` endpoints.
|
|
|
|
Values in `sandbox.environment` that start with `$` are resolved from the
|
|
Gateway process environment when the provider starts. Missing variables resolve
|
|
to an empty string, matching the E2B provider.
|
|
|
|
## Lifecycle and contract
|
|
|
|
The provider derives a stable local ID from `(user_id, thread_id)`. A released
|
|
sandbox enters an in-process warm pool and only the same scope may reclaim it.
|
|
Create returns only after the SDK readiness check and DeerFlow's
|
|
`/mnt/user-data/{workspace,uploads,outputs}` bootstrap succeed. A bootstrap
|
|
failure explicitly destroys the newly created remote sandbox.
|
|
Each remote has an independent SDK connection transport. Before an operation,
|
|
the adapter renews `sandbox_timeout`; commands use `bash_command_timeout` when
|
|
the caller supplies no timeout and extend the renewal horizon when necessary.
|
|
Operations are serialized per remote so a shorter renewal cannot overwrite the
|
|
horizon of an in-flight long command.
|
|
Setting `sandbox_timeout: 0` selects explicit-cleanup mode and disables renewal.
|
|
|
|
The full DeerFlow surface is implemented:
|
|
|
|
- `execute_command` forwards per-call environment variables and positive
|
|
wall-clock timeouts through `RunCommandOpts`, preserving stdout, stderr, and
|
|
non-zero exit information in DeerFlow's string result.
|
|
- Text and binary file operations use OpenSandbox's native filesystem API.
|
|
Append is serialized as a read-modify-write because SDK 0.1.x has no append
|
|
primitive.
|
|
- `list_dir`, `glob`, and `grep` use portable `find`/`grep` commands and the
|
|
shared DeerFlow result parsers.
|
|
- All paths must be absolute and traversal-free. Artifact downloads are further
|
|
restricted to `/mnt/user-data`.
|
|
- Command-path HTTP 404, HTTP 410, unhealthy-session errors, and broken
|
|
transports evict the dead client so the next acquire cold-starts a
|
|
replacement. A file-path 404 remains an ordinary missing-file error.
|
|
|
|
`reset()` parks active clients for later cleanup; `shutdown()` destroys active
|
|
and warm remotes. Cross-process discovery and ownership coordination are not
|
|
implemented yet, so each Gateway process has its own warm pool and capacity
|
|
accounting.
|