d8ed8160c9
* fix(sandbox): stop list_dir from reporting failures as empty Remote providers swallowed find/client errors as [] and 2>/dev/null missing paths as empty stdout. ls_tool then told the agent the directory was (empty). Raise OSError/FileNotFoundError instead so the tool returns Error. * fix(sandbox): list_dir raises on missing local paths and uses find -H Empty stdout is not a missing path when find's start point is a symlink (E2B /mnt/acp-workspace). Dereference only the start point with find -H. LocalSandbox now raises FileNotFoundError for a non-directory root, matching remote providers. AIO maps a missing result.data to OSError rather than FileNotFoundError. * fix(sandbox): group AIO list_dir find type predicates Without parentheses, find PATH -maxdepth N -type f -o -type d applies -type d without maxdepth and can drop files from the listing. * fix(sandbox): distinguish list_dir command failure from missing path Tenki, Boxlite, and OpenSandbox treated any empty find stdout as FileNotFoundError, so a missing find binary (exit 127) or SDK error looked like a missing directory. Raise OSError when find status is outside (0, 1); keep FileNotFoundError for the find-ran-but-empty case. * fix(sandbox): apply list_dir exit-status contract to AIO and E2B Same gap as Tenki/Boxlite/OpenSandbox: empty find stdout with exit 127 was FileNotFoundError. Raise OSError when the status is outside (0, 1). * fix(sandbox): classify list_dir by find status not head status find | head under sh -lc reports head's exit code, so a missing find binary (127) became FileNotFoundError. Record find's own status after the bounded listing, treat SIGPIPE 141 as truncation success, and add a shell-level regression test. * test(auth): include projects permissions in /me contract pins #5265 added projects:read/write/delete to the registered route set. The /auth/me tests still pinned the pre-projects list, so CI failed after merging main. * fix(sandbox): do not treat missing list_dir marker as success The generated script ended on `rm -f`, so process status was 0/1 even when find's marker never landed. Both codes are in _FIND_OK, and the parser fallback then classified an empty listing as FileNotFoundError — the 127 misclassification this helper was meant to close. Exit with find's status (126 if unknown). A missing marker is now OSError unless the process status is already a non-OK failure. * test(sandbox): emit list_dir status marker in provider fixtures Parser now requires __DF_FIND_STATUS__ and refuses marker-less stdout. Update AIO/Boxlite/E2B stubs and OpenSandbox/Tenki find fakes so listings carry :0 and missing paths carry :1 with matching exit codes. * style(sandbox): format list dir test fixture * style(sandbox): format remote list dir helper * docs(sandbox): keep guidance within the tested size budget --------- Co-authored-by: Willem Jiang <willem.jiang@gmail.com>
OpenSandbox backend
Runs DeerFlow sandboxes on OpenSandbox,
using the synchronous Python SDK behind DeerFlow's Sandbox and
SandboxProvider contracts.
Installation and configuration
Install the optional SDK, then select the provider:
pip install "deerflow-harness[opensandbox]"
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_commandforwards per-call environment variables and positive wall-clock timeouts throughRunCommandOpts, 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, andgrepuse portablefind/grepcommands 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.