Implementation:OpenHands OpenHands SaasNestedConversationManager Create Runtime

Knowledge Sources	OpenHands
Domains	Distributed_Systems, Conversation_Management
Last Updated	2026-02-11 21:00 GMT

Overview

Concrete tool for provisioning isolated remote container runtimes for agent conversations, provided by the OpenHands enterprise conversation management layer.

Description

The _create_runtime method is a private async method responsible for constructing and initializing a RemoteRuntime instance for a given conversation. It performs the following operations:

1. Resolves the LLM configuration from the LLMRegistry based on the user's settings.
2. Looks up the appropriate Agent class and validates compatibility with the selected LLM.
3. Instantiates a RemoteRuntime container with the conversation ID as the container label.
4. Configures the runtime with sandbox parameters (image, resource limits, network policies).
5. Waits for the container to reach a ready state before returning.

The method takes a ProviderHandler that encapsulates the validated authentication credentials for the LLM provider, ensuring that the runtime is created with fresh, valid tokens.

Usage

This method is called internally by maybe_start_agent_loop during the resource provisioning phase. It should not be called directly by external consumers; instead, use the public maybe_start_agent_loop entry point which handles distributed locking and the full lifecycle.

Code Reference

Source Location

• Repository: OpenHands
• File: enterprise/server/saas_nested_conversation_manager.py
• Lines: L865-971

Signature

async def _create_runtime(
    self,
    sid: str,
    user_id: str,
    settings: Settings,
    provider_handler: ProviderHandler,
) -> RemoteRuntime

Import

from enterprise.server.saas_nested_conversation_manager import SaasNestedConversationManager

I/O Contract

Inputs

Name	Type	Required	Description
sid	str	Yes	The unique session/conversation identifier that becomes the container label and runtime key.
user_id	str	Yes	The authenticated user identifier, used for scoping resource quotas and audit logging.
settings	Settings	Yes	Application settings containing sandbox image, LLM model selection, agent name, and resource limit parameters.
provider_handler	ProviderHandler	Yes	An object encapsulating validated LLM provider credentials (API keys, OAuth tokens) for the selected provider.

Outputs

Name	Type	Description
return	RemoteRuntime	A fully initialized remote runtime instance that is ready to accept agent loop commands. The runtime exposes an HTTP API URL for configuration injection and event streaming.

Usage Examples

Basic Usage

# Internal usage within SaasNestedConversationManager
# This method is private and called by maybe_start_agent_loop

provider_handler = await self._get_provider_handler(settings, user_id)
runtime = await self._create_runtime(
    sid="conv_abc123",
    user_id="user_42",
    settings=current_settings,
    provider_handler=provider_handler,
)

# Runtime is now ready; its API URL can be used for configuration
print(f"Runtime API: {runtime.api_url}")

Error Handling

try:
    runtime = await self._create_runtime(
        sid=sid,
        user_id=user_id,
        settings=settings,
        provider_handler=provider_handler,
    )
except RuntimeError as e:
    # Provisioning failed; clean up the distributed lock
    await self._release_conversation_lock(sid)
    raise ConversationError(f"Failed to provision runtime: {e}")

Related Pages

Implements Principle

• Principle:OpenHands_OpenHands_Runtime_Provisioning

Environment

• Environment:OpenHands_OpenHands_SaaS_Server_Environment