Workflow:OpenHands OpenHands Third Party Runtime Integration
| Knowledge Sources | |
|---|---|
| Domains | Container_Orchestration, Cloud_Runtimes, Sandbox_Execution |
| Last Updated | 2026-02-11 21:00 GMT |
Overview
End-to-end process for provisioning, configuring, and executing agent workloads in third-party cloud sandbox environments (Daytona, E2B, Modal, Runloop).
Description
This workflow describes how OpenHands integrates with four third-party cloud sandbox providers to execute agent code in isolated environments. All four runtimes extend the ActionExecutionClient base class and follow a common pattern: authenticate with the provider API, create or attach to a sandbox/container, start the action execution server, execute commands, and handle cleanup. The implementations differ in their execution model (direct vs. action server), file handling, and provider-specific configuration.
Usage
Execute this workflow when deploying OpenHands with a third-party runtime backend instead of the default Docker-based runtime. This is appropriate for cloud deployments, environments without Docker access, or when provider-specific features (snapshots, prebuilt templates, GPU access) are needed.
Execution Steps
Step 1: Provider Authentication
Initialize the cloud provider SDK client using API credentials from environment variables. Each provider requires different authentication: Daytona uses an API key and URL, E2B uses SDK configuration, Modal uses a token ID and secret pair, and Runloop uses a bearer token.
Provider credentials:
- Daytona: DAYTONA_API_KEY, DAYTONA_API_URL (default: https://app.daytona.io/api)
- E2B: Configuration via E2B SDK config object
- Modal: MODAL_TOKEN_ID, MODAL_TOKEN_SECRET
- Runloop: RUNLOOP_API_KEY
Step 2: Sandbox Creation or Attachment
Create a new sandbox environment or attach to an existing one. Each provider has a different creation mechanism but all support reattaching to previously created sandboxes using cached identifiers.
Provider-specific creation:
- Daytona: CreateSandboxFromSnapshotParams with session ID label, auto-stop interval
- E2B: E2BSandbox instantiation with SDK config, sandbox ID cache for reattachment
- Modal: modal.Sandbox.create() with app lookup, image definition, encrypted ports
- Runloop: devboxes.create() with prebuilt "openhands" template, LARGE resource size
Key considerations:
- All providers support attaching to existing sandboxes via ID or label lookup
- Sandbox ports typically include 4444 (action server) and 4445 (VSCode)
- Workspace base mounting is not supported by E2B or Modal (warnings logged)
Step 3: Action Execution Server Startup
Start the action execution server inside the sandbox to receive and process commands. Three of the four runtimes (Daytona, Modal, Runloop) use an HTTP-based action execution server; E2B uses direct execution through its SDK.
Execution models:
- Action Server (Daytona, Modal, Runloop): HTTP server at port 4444 receives command requests
- Direct Execution (E2B): Commands executed via sandbox.execute() and sandbox.run_code()
Key considerations:
- Runloop wraps the startup command in a Mamba/Poetry environment setup
- Modal waits 20 seconds after creation to avoid RemoteProtocolError
- Daytona creates named sessions for command execution
Step 4: Command Execution
Execute agent commands within the sandbox environment. For action server runtimes, commands are sent as HTTP requests. For E2B, commands are executed directly through the SDK, returning exit codes and output.
Key considerations:
- Daytona uses SessionExecuteRequest with async execution enabled
- E2B returns tuple (exit_code, output) from sandbox.execute()
- E2B supports IPython execution via sandbox.run_code()
- Timeouts are configurable per command
Step 5: File Operations
Handle file uploads, downloads, reads, writes, and listings within the sandbox filesystem. E2B provides a dedicated E2BFileStore wrapper; other runtimes delegate file operations to the action execution server.
Provider-specific file handling:
- E2B: E2BFileStore wrapping sandbox.filesystem (read, write, list, copy_to)
- Daytona, Modal, Runloop: File operations through action execution server API
Step 6: Cleanup and Shutdown
Terminate the sandbox environment when the conversation ends. Each provider has specific shutdown behavior and optional deletion settings.
Provider-specific cleanup:
- Daytona: Configurable via DAYTONA_DELETE_ON_CLOSE (default false)
- E2B: Sandbox lifecycle managed by E2B platform
- Modal: Sandbox timeout at 60 minutes, explicit termination available
- Runloop: Devbox shutdown via API