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

> Learn how to set up SkyPilot deployment for cloud training with AReaL. Effortlessly launch jobs on GCP, AWS, or Kubernetes using YAML templates and sky launch.

- Repository: [inclusionAI/areal](https://github.com/inclusionai/areal)
- Tags: how-to-guide
- Published: 2026-03-04

---

**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`](https://github.com/inclusionai/areal/blob/main/docs/tutorial/installation.md).

```bash

# 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`](https://github.com/inclusionai/areal/blob/main/examples/skypilot/single_node.sky.yaml). This template provisions a single VM with the following key specifications:

```yaml
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:

```yaml
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`](https://github.com/inclusionai/areal/blob/main/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.

```bash

# 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:

```bash
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`](https://github.com/inclusionai/areal/blob/main/areal/utils/saver.py) and [`areal/utils/recover.py`](https://github.com/inclusionai/areal/blob/main/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`](https://github.com/inclusionai/areal/blob/main/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`](https://github.com/inclusionai/areal/blob/main/docs/tutorial/installation.md)
- **Choose the appropriate YAML template**: [`examples/skypilot/single_node.sky.yaml`](https://github.com/inclusionai/areal/blob/main/examples/skypilot/single_node.sky.yaml) for single-node jobs or [`examples/skypilot/ray_cluster.sky.yaml`](https://github.com/inclusionai/areal/blob/main/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`](https://github.com/inclusionai/areal/blob/main/areal/utils/saver.py) and [`areal/utils/recover.py`](https://github.com/inclusionai/areal/blob/main/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`](https://github.com/inclusionai/areal/blob/main/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`](https://github.com/inclusionai/areal/blob/main/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`](https://github.com/inclusionai/areal/blob/main/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.