Implementation:OpenHands OpenHands DaytonaRuntime Connect
| Knowledge Sources | |
|---|---|
| Domains | Cloud_Infrastructure, Runtime_Management |
| Last Updated | 2026-02-11 21:00 GMT |
Overview
Concrete tool for creating and connecting to a Daytona cloud sandbox, provided by the OpenHands third-party runtime layer.
Description
DaytonaRuntime.connect orchestrates the full sandbox creation lifecycle for the Daytona provider. It calls _create_sandbox() to provision a new Daytona sandbox with the configured container image, workspace directory, and environment variables, then starts the action execution server inside the sandbox, and finally waits until the sandbox reports healthy via _wait_until_alive().
The internal _create_sandbox() method (L121-136) constructs a CreateSandboxParams object with the runtime image, environment variables, and resource limits, then calls the Daytona SDK to provision the sandbox. The sandbox is assigned a unique identifier that is stored on the runtime instance for subsequent operations.
Other third-party runtimes implement the same lifecycle with provider-specific details:
- E2BRuntime.connect (e2b_runtime.py:L90-152) creates an E2B sandbox using template IDs and the E2B SDK, then initializes the E2BBox and E2BFileStore wrappers.
- ModalRuntime.connect (modal_runtime.py:L121-166) creates a Modal sandbox with GPU/CPU resources, mounts, and network configuration using the Modal SDK.
- RunloopRuntime.connect (runloop_runtime.py:L129-164) creates a Runloop devbox, waits for it to reach "running" status, and establishes a tunnel for communication.
All four runtimes share the _wait_until_alive() health check, which uses tenacity retry logic with a 120-second timeout and 1-second polling interval.
Usage
Call connect() immediately after constructing a DaytonaRuntime instance. This is an async method that must be awaited. After it returns, the sandbox is fully operational and ready to execute agent actions.
Code Reference
Source Location
- Repository: OpenHands
- File:
third_party/runtime/impl/daytona/daytona_runtime.py - Lines: L184-233 (connect), L121-136 (_create_sandbox)
Signature
async def connect(self) -> None:
Import
from third_party.runtime.impl.daytona.daytona_runtime import DaytonaRuntime
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| self | DaytonaRuntime | Yes | An initialized DaytonaRuntime instance with authenticated Daytona client (constructed via __init__) |
Outputs
| Name | Type | Description |
|---|---|---|
| None | None | The method returns None. On success, the runtime's internal sandbox reference is populated and the action server is responsive. On failure, an exception is raised. |
Usage Examples
Basic Usage
from third_party.runtime.impl.daytona.daytona_runtime import DaytonaRuntime
# After constructing the runtime instance:
runtime = DaytonaRuntime(
config=openhands_config,
event_stream=event_stream,
sid="session-002",
)
# Create the sandbox and wait until it is alive:
await runtime.connect()
# The sandbox is now operational. Execute actions:
observation = await runtime.run(cmd_action)
Attach to Existing Sandbox
runtime = DaytonaRuntime(
config=openhands_config,
event_stream=event_stream,
sid="session-002",
attach_to_existing=True,
)
# When attach_to_existing is True, connect() locates
# an existing sandbox by session ID instead of creating a new one.
await runtime.connect()