Principle:OpenHands OpenHands Action Server Startup
| Knowledge Sources | |
|---|---|
| Domains | Cloud_Infrastructure, Runtime_Management |
| Last Updated | 2026-02-11 21:00 GMT |
Overview
Action Server Startup is the principle of launching an action execution server inside a cloud sandbox to receive and process agent commands over HTTP.
Description
Once a cloud sandbox is provisioned, it is an empty container with no mechanism for the orchestrator to send agent actions (shell commands, file edits, IPython executions) to it. The action execution server is a lightweight HTTP server that runs inside the sandbox, listens on a designated port, and exposes endpoints for executing actions and reporting health status.
This follows the sidecar pattern: the action server is a subordinate process that runs alongside the agent's workspace inside the sandbox. It mediates between the external orchestrator (which communicates via HTTP) and the sandbox's internal environment (which executes commands locally). The orchestrator never directly accesses the sandbox's shell or filesystem; all interactions are proxied through the action server.
The action server provides several critical endpoints:
- /alive -- Health check endpoint used by _wait_until_alive() to confirm the server is ready.
- /execute_action -- Receives serialized action objects and returns observation results.
- /upload_file, /download_file -- File transfer endpoints for moving data in and out of the sandbox.
The startup command is generated by get_action_execution_server_startup_command(), a shared utility that produces the correct command line for launching the server with the appropriate port, working directory, and plugin configuration.
Important exception: E2B does not use the action server pattern. Instead, E2B directly executes commands through its SDK's built-in execution API (E2BBox.execute). This is because E2B provides native command execution and filesystem access through its API, making the sidecar server unnecessary.
Usage
Action Server Startup occurs during the connect() phase, after the sandbox container has been created but before the runtime reports itself as alive. It is an internal step that is not directly invoked by users or the orchestrator.
Theoretical Basis
The sidecar pattern places a helper process alongside the primary workload to handle cross-cutting concerns (in this case, action dispatching and health reporting).
SANDBOX CONTAINER:
+-----------------------------------------+
| |
| [Action Execution Server] (sidecar) |
| - Listens on port P |
| - Endpoints: /alive, /execute_action |
| - /upload_file, /download_file |
| |
| [Agent Workspace] (/workspace) |
| - User files |
| - Installed plugins |
| |
+-----------------------------------------+
ORCHESTRATOR (external):
1. CALL _create_sandbox()
2. CALL _start_action_execution_server()
-> Executes startup command inside sandbox
-> Command: get_action_execution_server_startup_command(
port, working_dir, plugins, is_root, ...)
3. CALL _wait_until_alive()
-> Polls GET sandbox_url/alive until 200 response
4. Runtime is ready for action execution
EXCEPTION (E2B):
E2B skips step 2. It uses its native SDK execution
API directly, bypassing the sidecar pattern entirely.
The startup command is constructed by a shared utility function to ensure consistency across Daytona, Modal, and Runloop runtimes. Only E2B deviates from this pattern.