Implementation:Ray project Ray RuntimeEnv

Knowledge Sources	Ray
Domains	Distributed_Computing, Java_Runtime
Last Updated	2026-02-13 16:00 GMT

Overview

Public API interface for constructing, inspecting, and serializing runtime environment specifications that can be attached to Ray jobs, actors, or tasks.

Description

RuntimeEnv is a Java interface with CRUD methods for named environment fields: set/setJsonStr to add fields by object or JSON string, get/getJsonStr to retrieve them with generic type deserialization support, contains and remove for membership testing and deletion, and isEmpty to check for an empty configuration. Serialization is handled by serialize() and serializeToRuntimeEnvInfo(). A static deserialize method delegates to Ray.internal().deserializeRuntimeEnv(). Configuration options are managed through setConfig/getConfig using RuntimeEnvConfig. A nested Builder class creates instances via Ray.internal().createRuntimeEnv().

Usage

Use RuntimeEnv to declaratively specify dependencies (JARs, environment variables, etc.) that Ray provisions on workers before task execution. Attach a RuntimeEnv to jobs, actors, or tasks to ensure reproducible and isolated execution environments across a heterogeneous cluster.

Code Reference

Source Location

• Repository: Ray
• File: java/api/src/main/java/io/ray/api/runtimeenv/RuntimeEnv.java

Signature

public interface RuntimeEnv {

  void set(String name, Object value) throws RuntimeEnvException;
  void setJsonStr(String name, String jsonStr) throws RuntimeEnvException;
  <T> T get(String name, Class<T> classOfT) throws RuntimeEnvException;
  String getJsonStr(String name) throws RuntimeEnvException;
  boolean contains(String name);
  boolean remove(String name) throws RuntimeEnvException;
  String serialize() throws RuntimeEnvException;
  boolean isEmpty();
  String serializeToRuntimeEnvInfo() throws RuntimeEnvException;
  static RuntimeEnv deserialize(String serializedRuntimeEnv) throws RuntimeEnvException { ... }
  void setConfig(RuntimeEnvConfig runtimeEnvConfig);
  RuntimeEnvConfig getConfig();

  public static class Builder {
    public RuntimeEnv build() { ... }
  }
}

Import

import io.ray.api.runtimeenv.RuntimeEnv;

I/O Contract

Input

Method	Parameter	Type	Description
set	name	String	The built-in name or runtime env plugin name (see RuntimeEnvName)
set	value	Object	Primitive data type or POJO value for the field
setJsonStr	jsonStr	String	JSON string representation of the field value
get	classOfT	Class<T>	Target class for deserialization
deserialize	serializedRuntimeEnv	String	Serialized runtime env string to reconstruct

Output

Method	Return Type	Description
get	T	Deserialized field value of the specified type
getJsonStr	String	JSON string of the named field
contains	boolean	Whether the named field exists
remove	boolean	Whether an existing field was removed
serialize	String	Serialized runtime env string
isEmpty	boolean	Whether the runtime env has no fields
deserialize	RuntimeEnv	Reconstructed RuntimeEnv instance
getConfig	RuntimeEnvConfig	The associated runtime env configuration

Usage Examples

// Create a RuntimeEnv using the builder
RuntimeEnv runtimeEnv = new RuntimeEnv.Builder().build();

// Set environment variables
Map<String, String> envVars = new HashMap<>();
envVars.put("MY_ENV_VAR", "value");
runtimeEnv.set("env_vars", envVars);

// Set runtime environment via JSON
runtimeEnv.setJsonStr("env_vars", "{\"KEY\": \"VALUE\"}");

// Check if a field is present
boolean hasEnvVars = runtimeEnv.contains("env_vars");

// Serialize and deserialize
String serialized = runtimeEnv.serialize();
RuntimeEnv restored = RuntimeEnv.deserialize(serialized);

// Configure runtime env options
RuntimeEnvConfig config = new RuntimeEnvConfig();
config.setSetupTimeoutSeconds(60);
runtimeEnv.setConfig(config);

Related Pages

• Environment:Ray_project_Ray_Java_Build_Environment