How to Set Up SkyPilot Deployment for Cloud-Based Training with AReaL

AReaL integrates natively with SkyPilot to launch cloud-based training jobs on GCP, AWS, or Kubernetes using pre-configured YAML templates and the sky launch command.

The inclusionai/areal repository provides first-class support for SkyPilot, a cloud-agnostic orchestration tool that abstracts virtual machines, storage, and networking. This integration allows you to scale from single-node experiments to multi-node distributed training without modifying your AReaL code.

Installing SkyPilot

Before deploying to the cloud, install SkyPilot with provider-specific extras. The installation instructions are documented in docs/tutorial/installation.md.

# Inside your AReaL virtual environment

pip install -U "skypilot[gcp,kubernetes]"

This command installs the SkyPilot CLI alongside GCP and Kubernetes dependencies. AWS support is included by default, while GCP and Kubernetes require the optional extras specified in brackets.

Configuring SkyPilot YAML Templates

AReaL provides ready-made YAML configurations under examples/skypilot/ that define compute resources, container images, and storage mounts. You must select the template that matches your scaling requirements.

Single-Node Training Configuration

For quick experiments or debugging, use examples/skypilot/single_node.sky.yaml. This template provisions a single VM with the following key specifications:

name: areal-test-skypilot
resources:
  cloud: gcp
  instance_type: n1-standard-8
  accelerators: [{type: T4, count: 1}]
image: ghcr.io/inclusionai/areal:latest
setup: |
  pip install -e .
  pip install -U "skypilot[gcp,kubernetes]"
envs:
  AREAL_CONFIG: examples/math/gsm8k_rl.py
file_mounts:
  /tmp/areal-bucket: {source: gs://my-sky-bucket, type: CLOUD}

The resources stanza allocates CPU, memory, and GPU, while file_mounts attaches a persistent cloud bucket (e.g., gs://my-sky-bucket) for checkpoint storage. The setup commands install AReaL in editable mode inside the provisioned container.

Multi-Node Ray Cluster Configuration

For distributed PPO or GRPO training across multiple nodes, use examples/skypilot/ray_cluster.skyyaml. This template defines separate resource groups for head and worker nodes:

name: areal-ray-cluster
resources:
  - name: head
    count: 1
    instance_type: n1-standard-8
    accelerators: [{type: T4, count: 1}]
  - name: worker
    count: 3
    instance_type: n1-standard-8
    accelerators: [{type: T4, count: 1}]
setup: |
  pip install -e .
  pip install ray[tune]==2.9.0
envs:
  RAY_ADDRESS: auto
file_mounts:
  /tmp/areal-bucket: {source: gs://my-sky-bucket, type: CLOUD}

The RAY_ADDRESS: auto environment variable enables the Ray worker nodes to discover the head node automatically. According to the source code in areal/infra/launcher/ray_launcher.py, AReaL's Ray launcher reads these SkyPilot-injected environment variables to construct the head-worker cluster topology.

Launching Your Cloud Training Job

After selecting your YAML template, use the sky launch command to provision infrastructure and start training. The --infra flag selects your cloud provider without requiring code changes.

# Launch single-node training on GCP

sky launch -c areal-test examples/skypilot/single_node.sky.yaml --infra gcp

# Launch multi-node Ray cluster on AWS

sky launch -c areal-test examples/skypilot/ray_cluster.sky.yaml --infra aws

# Launch on Kubernetes

sky launch -c areal-test examples/skypilot/single_node.sky.yaml --infra k8s

SkyPilot executes the following sequence:

1. Provisions VMs or Kubernetes pods matching the YAML specifications
2. Pulls the Docker image ghcr.io/inclusionai/areal:latest
3. Runs the entry-point command defined in the YAML (e.g., python examples/math/gsm8k_rl.py)
4. Streams logs to your local terminal and syncs artifacts to the mounted bucket

When training completes, tear down the resources to stop billing:

sky down -c areal-test

Architecture and Integration

Understanding how SkyPilot interacts with AReaL's internals ensures you can debug distributed runs and optimize checkpointing.

SkyPilot as Outer Orchestrator

SkyPilot acts strictly as an infrastructure provisioner. It does not interfere with AReaL's internal distributed launchers found in areal/infra/launcher/. Instead, SkyPilot ensures the requested VMs are running, mounts the specified cloud buckets, and hands control to AReaL's own launcher scripts.

Checkpoint Persistence

The file_mounts stanza in your YAML attaches a SkyPilot cloud bucket to every node at the specified mount point (e.g., /tmp/areal-bucket). AReaL's checkpointing utilities in areal/utils/saver.py and areal/utils/recover.py automatically write model weights and logs to this mounted path. This design guarantees that training artifacts survive cluster termination, allowing you to resume training later using the recovered checkpoints.

Scalability Across Providers

The separation of concerns between SkyPilot and AReaL enables provider-agnostic scaling. For multi-node runs, areal/infra/launcher/ray_launcher.py initializes the Ray cluster using environment variables injected by SkyPilot. You can swap between GCP, AWS, and Kubernetes by changing only the --infra flag in your launch command—no modifications to AReaL's trainer, engine, or workflow modules are required.

Summary

• Install SkyPilot using pip install -U "skypilot[gcp,kubernetes]" as documented in docs/tutorial/installation.md
• Choose the appropriate YAML template: examples/skypilot/single_node.sky.yaml for single-node jobs or examples/skypilot/ray_cluster.sky.yaml for distributed Ray clusters
• Launch with sky launch -c <cluster-name> <yaml-file> --infra <gcp|aws|k8s> to provision infrastructure on your chosen provider
• Persist checkpoints automatically via file_mounts cloud buckets, managed by areal/utils/saver.py and areal/utils/recover.py
• Teardown resources with sky down when training completes to minimize cloud costs

Frequently Asked Questions

Does SkyPilot modify AReaL's distributed training code?

No. SkyPilot provisions the underlying VMs or Kubernetes pods and mounts storage, but it does not alter AReaL's distributed logic. The areal/infra/launcher/ray_launcher.py script reads environment variables injected by SkyPilot to initialize Ray clusters independently, allowing AReaL's trainer and engine modules to run unchanged.

How do I ensure my training checkpoints survive cluster termination?

Configure a file_mounts entry in your YAML to attach a cloud bucket (e.g., gs://my-bucket). AReaL's checkpointing utilities in areal/utils/saver.py write directly to this mounted path. Since the bucket persists independently of the VMs, your checkpoints remain available after running sky down.

Can I switch between AWS and GCP without changing the YAML file?

Yes. The --infra flag in the sky launch command overrides the cloud provider specified in the YAML. For example, you can launch the same single_node.sky.yaml on GCP with --infra gcp or on AWS with --infra aws, provided you have configured credentials for both providers.

What Docker image should I specify for cloud deployment?

Use the official AReaL image ghcr.io/inclusionai/areal:latest or build a custom image from the repository. The YAML files under examples/skypilot/ reference this image in the image: field, ensuring that AReaL and all dependencies are pre-installed on every provisioned node.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}