Install a cluster

Enterprise only

Bring your own compute (BYOC) is available on organizations with an Enterprise plan. Without it, the Bring your own compute menu item is hidden. See Plan permissions.

Connecting your hardware: register the cluster, install the Arena agent into it, add resource classes, then check a run lands. BYOC covers self-managed Kubernetes and cloud Kubernetes such as EKS, GKE, or Nebius.

Prerequisites

• Enterprise organization and org Admin role

• Arena CLI installed (pip install "agilerl[arena]") and arena login or ARENA_API_KEY if you use the CLI (Authentication)

• kubectl pointed at the cluster you will install into, plus helm

• An S3-compatible bucket the cluster can reach, and a Kubernetes Secret with its credentials in the agent namespace (arena)

• To provision a Kubernetes cluster with the CLI (arena cluster provision): terraform and the Brev CLI (brev) on your PATH

Nebius is the only cloud Arena can create a cluster on, and that creation runs through the Arena CLI, not the web app. Two orders work: register in Arena first (Cloud provider set to Nebius), then run arena cluster provision nebius --spec <file> --create-state-bucket and install the agent; or do the whole thing from the terminal with arena cluster provision nebius --spec <file> --register-and-install. For Custom, you bring a Kubernetes cluster you already run and install the agent into it.

Step 1: Register the cluster

UI path (most teams):

1. Profile menu → Bring your own compute.

2. Register new cluster — set Name, Cloud provider, and (for Custom) the storage endpoint, bucket, and Secret name.

CLI path: arena cluster register creates or updates the cluster from your terminal. Reusing a name updates that cluster rather than adding a second one. Registering does not create a resource class; classes are a separate step.

Both paths enable the BYOC provider for the org. Pass --skip-enable if it is already enabled.

Step 2: Install the agent

Arena CLI (recommended)

Install the CLI first (pip install "agilerl[arena]" — see Arena CLI). Copy the command Bring your own compute generates after you register, or run:

arena login
arena cluster register --name 'corp-k8s' \
  --storage-endpoint 'https://s3.corp.example.com' \
  --storage-bucket 'arena-data' \
  --storage-secret-name 'arena-storage' \
  --install --no-write

--install installs the agent (Helm release arena-byoc-agent) into the arena namespace using your current kube context. --no-write keeps chart files off disk.

See BYOC CLI for the full flag list, token rotation, and unregistering.

Helm or install package

Click Install on the cluster row, then open Install with Helm instead. From there you can copy the Helm command, download agent-helm-values.yaml, or download the install package arena-byoc-install-<cluster>.tar.gz — charts, values, and an INSTALL.md you can follow on a bastion with no CLI.

Step 3: Add resource classes

Back on Bring your own compute, expand your cluster row under BYOC clusters and click Add resource class to describe each worker pool: Name, Number of nodes, and the Compute resource (per worker node) fields. See Resource classes.

The cluster agent provisions Ray for each class. There is no per-class install and nothing to download per class. For a second hardware pool (different GPU type or site), add another class with a distinct Name and worker sizing, and use Worker node placement so it lands on the right machines.

Shared Ray data storage

Some runs need the same files on every node. Two optional settings under Advanced on the cluster form cover that: Ray data storage class and Ray data PVC size (CLI: --ray-data-storage-class-name, --ray-data-pvc-size). Field help reads “Optional StorageClass with ReadWriteMany access for agents that need shared storage” — point it at the ReadWriteMany class your platform team already runs (NFS, CephFS, or equivalent). Leave both empty and the cluster’s default applies.

Step 4: Verify

1. On Bring your own compute, the cluster row shows Connected, and the class Setup bundle column shows Current.

2. Create a test experiment, open Resources, and confirm your BYOC class appears (sorted above cloud classes, $0.00 per hour).

3. Train and confirm the run leaves Pending within the usual window (see troubleshooting).

Upgrade when Update recommended appears

Arena shipped a new training image. Classes on a registered cluster are rolled out by the cluster agent; keep the agent connected and the column returns to Current.

Teardown

Disconnect a registered cluster:

arena cluster unregister --name 'corp-k8s' --uninstall-helm

That archives the cluster in Arena, revokes its tokens, archives the classes bound to it, and uninstalls the arena-byoc-agent release. Add --uninstall-storage to also remove the bundled MinIO release (arena-byoc-storage in namespace storage) — that deletes checkpoints, metrics, and datasets on the cluster. Without those flags the CLI prompts per release; --yes skips the prompts and --kubeconfig points at a cluster that is not your current context.

You can also Archive the cluster in the UI and remove the Helm releases yourself.

Related

• Bring your own compute

• Resource classes

• BYOC overview

• BYOC CLI