Principle:OpenHands OpenHands Sandbox File Operations
| Knowledge Sources | |
|---|---|
| Domains | Cloud_Infrastructure, Runtime_Management |
| Last Updated | 2026-02-11 21:00 GMT |
Overview
Sandbox File Operations is the principle of reading, writing, listing, and deleting files within a cloud sandbox, abstracting provider-specific filesystem APIs behind a common FileStore interface.
Description
Agents frequently need to interact with the sandbox filesystem: reading source files, writing configuration, listing directories, and cleaning up temporary files. Each cloud provider exposes filesystem access differently -- some offer direct filesystem APIs in their SDK, while others only support HTTP-based file transfer through the action server.
OpenHands uses the adapter pattern to wrap these diverse filesystem APIs behind a common FileStore interface. The FileStore abstract class defines four fundamental operations:
- write(path, contents) -- Write string contents to a file at the given path.
- read(path) -- Read and return the contents of a file at the given path.
- list(path) -- List all files and directories at the given path.
- delete(path) -- Delete the file or directory at the given path.
Each provider implements this interface according to its capabilities:
E2B: Native SDK FileStore
E2B provides a direct filesystem API through its SDK. The E2BFileStore class wraps the E2B sandbox's filesystem methods (sandbox.filesystem.write, sandbox.filesystem.read, etc.) to implement the FileStore interface. This gives E2B low-latency, direct filesystem access without network overhead.
Daytona, Modal, Runloop: Action Server HTTP Delegation
These three runtimes do not have native filesystem APIs. Instead, they delegate file operations to the action execution server running inside the sandbox. File uploads use the /upload_file endpoint (HTTP POST with file data), file downloads use the /download_file endpoint (HTTP GET), and file listing and deletion are handled via shell commands executed through the /execute_action endpoint.
This dual approach -- native SDK for E2B and HTTP delegation for the others -- is transparent to the agent and orchestrator, which interact only with the abstract FileStore interface or the runtime's high-level file methods.
Usage
Sandbox File Operations are used throughout an agent session whenever the agent needs to read, write, list, or delete files in the sandbox workspace. They are also used internally by the runtime for plugin installation, configuration file setup, and log retrieval.
Theoretical Basis
The adapter pattern wraps provider-specific filesystem APIs behind a unified interface, allowing the orchestrator and agent to operate without knowledge of the underlying provider.
ABSTRACT CLASS FileStore:
method write(path: str, contents: str) -> None
method read(path: str) -> str
method list(path: str) -> list[str]
method delete(path: str) -> None
ADAPTER 1: E2BFileStore (direct SDK)
CLASS E2BFileStore IMPLEMENTS FileStore:
FIELD sandbox: E2BSandbox
method write(path, contents):
sandbox.filesystem.write(path, contents)
method read(path):
RETURN sandbox.filesystem.read(path)
method list(path):
RETURN sandbox.filesystem.list(path)
method delete(path):
sandbox.filesystem.remove(path)
ADAPTER 2: HTTP Delegation (Daytona, Modal, Runloop)
These runtimes inherit file methods from ActionExecutionClient:
method upload_file(local_path, sandbox_path):
HTTP POST /upload_file WITH file data
method download_file(sandbox_path):
HTTP GET /download_file?path=sandbox_path
method list_files(path):
execute("ls -la {path}") via action server
method delete_file(path):
execute("rm -rf {path}") via action server
COMMON CONTRACT:
INVARIANT: write then read returns same contents
INVARIANT: list after write includes written file
INVARIANT: read after delete raises error or returns empty
The adapter pattern ensures that adding a new provider with a different filesystem API only requires implementing a new FileStore adapter without changing the orchestrator or agent code.