Polyaxon v3 is coming →
Ray + RAGEN

Train agents with Ray and RAGEN

RAGEN builds agent reinforcement learning on verl and Ray. Polyaxon creates and tracks the KubeRay workload, while Ray coordinates the rollout and training actors across GPU workers.

Outcome

A two-node-shaped RayCluster component prepared for a versioned RAGEN image, persistent checkpoints, and framework-native logs.

Start the guideRead the Ray guide

Execution responsibilities

Polyaxon resolves

The component pins the image, inputs, secrets, resources, queue, and output contract.

Kubernetes places

The cluster schedules the requested accelerator topology and enforces namespace policy.

The framework trains

The training stack owns optimization while Polyaxon records status, logs, metadata, and artifacts.

Prerequisites

  • KubeRay and its CRDs installed, with the Polyaxon RayCluster integration enabled.
  • A validated image containing RAGEN, verl, Ray, the inference backend, and compatible CUDA libraries.
  • A GPU pool with working multi-node networking and storage for model data and checkpoints.

Run and validate

  1. 1

    Define the RAGEN Ray cluster

    Supply the digest of the RAGEN image your team built from a reviewed repository commit; the project does not publish a universal runtime image.

    version: 1.1kind: componentname: ragen-traininginputs:- name: image  type: strrun:  kind: raycluster  rayVersion: "2.58.0"  entrypoint: python train.py --config-name base  head:    container:      image: "{{ image }}"      resources:        limits:          nvidia.com/gpu: "8"  workers:    rollout-workers:      replicas: 1      minReplicas: 1      maxReplicas: 1      container:        image: "{{ image }}"        resources:          limits:            nvidia.com/gpu: "8"

    Build RAGEN and verl into one image at known commits, then pass its immutable registry digest as the `image` input. The guide intentionally does not invent a third-party image.

  2. 2

    Submit the operation

    Run the component through the target Polyaxon project, queue, preset, and approval path.

    polyaxon run -f ragen-ray.yaml -P image="$RAGEN_IMAGE"
  3. 3

    Inspect every Ray replica

    Confirm that workers join the head, actors see the expected GPUs, checkpoints land in durable storage, and reward and policy metrics reach the selected tracker.

    polyaxon ops dashboard

Production checklist

Pin the container image, framework versions, model revision, dataset revision, and training configuration.
Resolve registry, dataset, model, and tracking credentials through scoped Polyaxon connections.
Persist checkpoints and final artifacts outside the pod, and define resume behavior before a long run.
Set requests, limits, node selectors, tolerations, queue policy, timeout, and retry ownership explicitly.
Keep Ray, RAGEN, verl, vLLM or SGLang, PyTorch, CUDA, and NCCL versions as one tested compatibility set.

Troubleshooting

The pod remains Pending

Inspect quota, queue capacity, node selectors, taints, topology, and the requested accelerator count.

The process runs out of memory

Check model precision, sequence length, batch size, checkpointing, optimizer state, sharding, and actual device memory.

The run cannot read or save

Verify the referenced connection, secret scope, mounted path, object-store permissions, and available storage.

Sources

Official platform, library, model, and Polyaxon references used by this guide.

Continue

Compare AI platformsExplore MLOps