Rollout Networking
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Rollout Networking comprises the communication infrastructure and protocols used by the Osmosis SDK to facilitate interactions between the RolloutServer (where agent logic resides) and the TrainGate (the platform's coordination layer). This system manages the lifecycle of a remote rollout, from initial registration and health monitoring to the asynchronous execution of agent trajectories and LLM completions.
The networking layer ensures secure and reliable data transfer by enforcing API key authentication, implementing automated retry logic for transient failures, and providing utilities for network environment detection (such as public IP discovery). It is designed to handle high-concurrency workloads while maintaining strict adherence to the OpenAI-compatible completion protocol. Sources: osmosis_ai/rollout/__init__.py, osmosis_ai/rollout/server/app.py:53-73
Architecture and Protocol Flow
The networking architecture follows an asynchronous request-response pattern where the TrainGate initiates a rollout and the RolloutServer executes it in the background, making callbacks for completions.
Rollout Lifecycle Flow
The following diagram illustrates the network interaction between the Osmosis Platform/TrainGate and the local RolloutServer.
The lifecycle begins with a RolloutRequest sent to the /v1/rollout/init endpoint. The server returns a list of available tools and then transitions to background execution. During execution, the server communicates back to the TrainGate using the server_url provided in the initial request. Sources: osmosis_ai/rollout/server/app.py:246-340, osmosis_ai/rollout/core/schemas.py:355-385
Server Connectivity and Discovery
The SDK provides utilities to manage server visibility and registration within different network environments.
Public IP Detection
For servers sitting behind NAT or in cloud environments, the networking module includes tools to detect the public-facing IPv4 address. This is critical for registering the RolloutServer with the Osmosis Platform so that TrainGate can route requests correctly. Sources: osmosis_ai/rollout/network.py:12-45
Health Monitoring
The RolloutServer exposes two primary health endpoints:
- /health: A public endpoint returning basic server stats and agent status.
- /platform/health: An authenticated endpoint used by the Osmosis Platform to verify reachability and API key validity. Sources: osmosis_ai/rollout/server/app.py:195-236
Network Utility Functions
| Function | Description | Source |
|---|---|---|
detect_public_ip() | Attempts to find the public IPv4 via multiple external services (ident.me, etc). | network.py:12 |
validate_ipv4(ip) | Ensures a string is a valid IPv4 address. | network.py:73 |
is_private_ip(ip) | Checks if an IP address belongs to RFC1918 private ranges. | network.py:112 |
is_valid_hostname_or_ip(val) | Validates the format of a host identifier. | network.py:91 |
Client-Side Networking and Retries
The OsmosisLLMClient (and its concrete implementation OsmosisLLMClient) handles the outbound HTTP traffic from the agent to the TrainGate.
Retry Logic
The client implements exponential backoff for transient errors. It distinguishes between different classes of HTTP failures:
- 5xx Errors: Retried automatically based on
max_retriesconfiguration. - 4xx Errors: Generally not retried, as they indicate validation or authentication issues (e.g.,
OsmosisValidationError). - Timeouts: Retried during the completion callback phase to ensure the platform receives final trajectory data. Sources: osmosis_ai/rollout/client.py:248-275, osmosis_ai/rollout/config/settings.py:59-95
Configuration Parameters
The networking behavior is controlled via RolloutClientSettings:
| Attribute | Default | Description |
|---|---|---|
timeout_seconds | 300.0 | Global timeout for HTTP requests. |
max_retries | 3 | Retries for standard 5xx errors. |
complete_rollout_retries | 2 | Retries specifically for the final completion callback. |
max_connections | 100 | Size of the HTTP connection pool. |
Sources: osmosis_ai/rollout/config/settings.py:84-118
Authentication and Security
Networking security is enforced through Bearer Token authentication.
API Key Implementation
The RolloutRequest contains an api_key field. If present, the RolloutServer must include this key in the Authorization header for all callbacks to the TrainGate.
# Example of Header Extraction
provided = _extract_bearer_token(http_request.headers.get("authorization") or "")
if not validate_api_key(provided, api_key):
raise HTTPException(status_code=401, detail="Invalid API key")
Sources: osmosis_ai/rollout/server/app.py:53-73, osmosis_ai/rollout/core/schemas.py:408-412
Data Transfer Schemas
The rollout protocol uses specific Pydantic models to ensure type safety across the network.
RolloutRequest Validation
The RolloutRequest validates network-related fields before processing:
- server_url: Must use
httporhttpsschemes and have a valid host. - metadata: Limited to 1MB to prevent network congestion from oversized payloads.
- rollout_id: Validated to be non-empty and under 256 characters.
Sources: osmosis_ai/rollout/core/schemas.py:417-450
Conclusion
Rollout Networking provides a robust, asynchronous bridge between agent implementations and the Osmosis training platform. By combining strict schema validation, configurable retry strategies, and secure authentication, it enables complex agent trajectories to be executed reliably over standard HTTP/1.1 and HTTP/2 transports. This infrastructure is essential for the distributed nature of LLM training workflows where agents may be hosted across diverse network environments.