Bring your own compute (BYOC) CLI¶

Connect the Kubernetes cluster you train on (self-managed, or cloud Kubernetes such as EKS, GKE, or Nebius) and manage it from your terminal with arena cluster. The register command matches the one the Bring your own compute page generates after you fill in the cluster form.

Prerequisites¶

Arena CLI installed (pip install "agilerl[arena]")
arena login or ARENA_API_KEY (Authentication)
Enterprise organization
kubectl pointed at the cluster you want to connect, plus helm if you pass --install
To provision a Kubernetes cluster (arena cluster provision): terraform and the Brev CLI (brev) on your PATH

Register a cluster¶

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

Flag	Meaning
`--name`	Cluster name, unique per org. Reusing a name updates that cluster; it never creates a resource class.
`--storage-endpoint`	S3 API the cluster agent can reach
`--storage-bucket`	Bucket holding checkpoints and datasets
`--storage-secret-name`	Kubernetes Secret in the agent namespace with the bucket credentials
`--install`	Downloads charts from Arena and installs the agent against your current kube context
`--no-write`	Does not write chart files to disk
`--output-dir`	Where to write Helm values and the cluster token (default `./arena-cluster-NAME`)
`--agent-namespace`	Namespace for the agent Helm release (default `arena`)
`--skip-enable`	Skip enabling the BYOC provider for the org when it is already enabled
`--install-storage`	Mint bundled MinIO values and install the storage chart (`arena-byoc-storage` in namespace `storage`)
`--narrow-allowed-ips`	Omit `10.0.0.0/8` from WireGuard AllowedIPs (k3d/k3s)
`--lab`	Shortcut for `--install-storage --narrow-allowed-ips`. Still pass `--storage-endpoint`, `--storage-bucket`, and `--storage-secret-name` (PoC defaults: `http://minio.storage.svc:9000`, `arena-data`, `arena-storage`).
`--spec`	Read the settings above from a cluster YAML file instead of flags

On a re-register, --install-storage only reinstalls MinIO when Arena returns new storage values. When the cluster already has credentials, the CLI reuses them, prints “Existing MinIO credentials reused — storage chart not reinstalled”, and installs the agent chart alone.

Advanced flags¶

These match the Advanced section on Register BYOC cluster. Omit them unless you need a bucket prefix, customer inference DNS, Ingress or Gateway API, shared Ray data volumes, or a pinned preprocessing class.

Flag	Form field	Description
`--storage-prefix`	Storage prefix	Optional key prefix inside the bucket (for example `org-1/`). Checkpoints then look like `prefix/users/…/experiments/…/checkpoints/…`. Leave unset to write at the bucket root.
`--domain`	Domain	DNS suffix for inference hostnames, combined with `--hostname-template` into `{hostname}.{domain}`. Pass the Arena-managed domain the web form prefills (`{cluster}-{org}.byoc.agilerl.com`) and Arena publishes wildcard DNS for it. Pass your own (for example `corp.example.com`) and you own the records. Leave this and the hostname template empty to skip inference DNS. See Inference domain and DNS.
`--hostname-template`	Hostname template	Host part only, not a FQDN. Typical value: `inference-{deploymentId}`. `{deploymentId}` is replaced per deployment. If `--domain` is set and this flag is omitted, the template defaults to `inference-{deploymentId}`.
`--tls-secret-name`	TLS secret name	Kubernetes Secret for inference HTTPS when you use your own domain. Leave empty for the Arena-managed domain (`{cluster}-{org}.byoc.agilerl.com`) or for HTTP; Arena issues the managed-domain certificate.
`--gateway-api-parent-refs`	Gateway name, Gateway namespace, Section name	JSON list of Gateway API parent refs, or `@path.json` to read the list from a file. Each object needs `name`; `namespace` and `sectionName` are optional. `group` and `kind` are optional. Example: `'[{"name":"inference-gateway","namespace":"istio-system","sectionName":"https"}]'`. Omit to skip Gateway API routes.
`--ingress-class-name`	Ingress class name	`IngressClass` for inference Ingress objects when you use Ingress instead of (or as well as) Gateway API. Omit if you do not install Ingress.
`--ray-data-storage-class-name`	Ray data storage class	Kubernetes StorageClass with ReadWriteMany access (NFS, CephFS, or equivalent) so every Ray worker can mount the same data volume. Omit to use the cluster default. See Shared Ray data storage.
`--ray-data-pvc-size`	Ray data PVC size	Size of that shared PVC, Kubernetes quantity (for example `32Gi`). Used with `--ray-data-storage-class-name`.
`--preprocessing-resource-class`	Preprocessing resource class	Name of a BYOC class on this cluster that should run dataset preprocessing. Omit for None (no pinned class).

Create the credentials Secret in the agent namespace first if it does not exist:

kubectl create secret generic arena-storage -n arena \
  --from-literal=AWS_ACCESS_KEY_ID=<key> \
  --from-literal=AWS_SECRET_ACCESS_KEY=<secret>

The agent runs in the arena namespace as Helm release arena-byoc-agent. Connectivity shows Connected on the cluster row once the agent polls Arena. Resource classes are separate: add them on Bring your own compute after the cluster is connected.

Rotate the cluster token¶

Issue a fresh token and update the Secret the agent reads:

arena cluster rotate-token --name 'corp-k8s'

Pass --kubeconfig when the cluster is not your current context, and --yes to skip the confirmation prompt. --agent-namespace and --secret-name override where the CLI writes the token; both default to what Helm reports for arena-byoc-agent.

Unregister¶

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

Unregister archives the cluster in Arena, revokes its tokens, and archives the resource classes bound to it. It can also clean up Helm on your side:

Flag	Meaning
`--uninstall-helm`	Uninstall the agent release (`arena-byoc-agent`) without prompting. Leaves MinIO alone.
`--uninstall-storage`	Uninstall the bundled MinIO release (`arena-byoc-storage`, namespace `storage`). This deletes checkpoints, metrics, and datasets on the cluster.
`--yes`	Unregister without prompting
`--kubeconfig`	Kubeconfig for the agent cluster (defaults to `arena-cluster-NAME/kubeconfig` when that file exists)

Without the uninstall flags the CLI lists the releases it found and asks about each one; MinIO is kept unless you confirm. With --yes and no uninstall flag, nothing is uninstalled — remove the releases yourself.

Provision a cloud cluster¶

Nebius is the only cloud Arena can create a cluster on, and that creation runs through the Arena CLI, not the web app. You can register in Arena first and provision afterwards, or do both from the terminal. plan / provision / destroy need terraform and the Brev CLI (brev) on PATH (in addition to Nebius credentials). Start from a spec file:

arena cluster generate-spec --provider nebius --name lab-cluster
arena cluster plan --spec lab-cluster.yaml
arena cluster provision nebius --spec lab-cluster.yaml --register-and-install

Command	What it does
`generate-spec`	Writes a starter YAML spec you fill in with your cloud project IDs
`plan`	Shows what would be created, without creating it
`provision`	Creates the cluster and writes a kubeconfig; add `--register-and-install` to register with Arena and install the agent in one go
`status`	Prints the cluster outputs (endpoints, node groups) for a provisioned spec
`destroy`	Tears the cluster down; add `--delete-storage` to remove the object storage bucket, or `--delete-storage-project` to remove the storage project as well

If you already registered the cluster in Arena, run provision without --register-and-install, then install the agent with the command or Helm values from Install on the cluster row.

Cluster spec (Nebius)¶

generate-spec writes a YAML file (default ./NAME.yaml). The only supported --provider today is nebius. Edit the placeholders (tenant-..., project IDs) before plan or provision. Command-line flags override the same keys in the file.

terraform_state.bucket is required and must be a dedicated Object Storage bucket, not values.storage_bucket_name. If that state bucket does not exist yet, pass --create-state-bucket on provision.

Two Nebius projects: values.project_id is the compute project (cluster, VPC, subnet, shared filesystem). values.storage_project_id is the storage project (experiment bucket, IAM, Terraform state bucket). Omit either project ID and set values.region so Terraform can create the missing project.

Example after arena cluster generate-spec --provider nebius --name lab-cluster, with IDs filled in:

provider: nebius
name: lab-cluster
terraform_state:
  bucket: lab-cluster-tfstate
values:
  tenant_id: tenant-abc123
  region: eu-north1
  project_id: project-compute
  storage_project_id: project-storage
  subnet_id: vpcsubnet-xyz
  storage_bucket_name: lab-cluster-data
  storage_endpoint: https://storage.eu-north1.nebius.cloud
  arena:
    min_node_count: 2
    max_node_count: 10
    platform: cpu-e2
    preset: 2vcpu-8gb
  workers:
    - name: workers
      min_node_count: 0
      max_node_count: 10
      platform: gpu-h100-sxm
      preset: 1gpu-16vcpu-200gb
      gpu_drivers_preset: cuda13.0
  object_storage:
    size_gib: 1024
  shared_filesystem:
    provision: true
    type: NETWORK_SSD
    size_gib: 256
    mount_tag: csi-storage
  inference:
    domain: lab-cluster-9.byoc.agilerl.com
    hostname_template: "inference-{deploymentId}"
  gateway_api:
    enable: true
    gateway_name: arena

Key	Required	Meaning
`provider`	Yes	Must be `nebius`.
`name`	Yes	Cluster name in Arena. Default from generate-spec is `arena-nebius` if you omit `--name`.
`terraform_state.bucket`	Yes	Dedicated bucket for Terraform state. Optional `key` defaults to `clusters/<name>/terraform.tfstate`.
`values.tenant_id`	Yes	Nebius tenant ID.
`values.region`	If a project ID is omitted	Region used when Terraform creates a project (for example `eu-north1`).
`values.project_id`	No	Existing compute project. Omit (with `region`) to create one.
`values.storage_project_id`	No	Existing storage project. Omit (with `region`) to create one. `destroy` keeps this project unless you pass `--delete-storage-project`.
`values.subnet_id`	No	Existing subnet. Requires `project_id`. Omit to let Terraform create VPC and subnet.
`values.service_account_id`	No	Existing node service account. Omit to create an `arena` account in the tenant admins group.
`values.storage_bucket_name`	Yes	Experiment-data bucket (checkpoints, datasets).
`values.storage_endpoint`	Yes	S3 API for that bucket (region-specific Nebius storage URL).
`values.arena`	No	CPU node group for the Arena agent (defaults shown above).
`values.workers`	Yes (at least one)	GPU worker pools. `preset` must look like `1gpu-16vcpu-200gb`. `platform` is the GPU type (`gpu-h100-sxm`, `gpu-h200-sxm`, `gpu-l40s-a`, and similar). With `--register-and-install`, each worker becomes a BYOC class named `<cluster>-<worker.name>`.
`values.object_storage.size_gib`	Yes	Max size of the experiment bucket, in GiB.
`values.shared_filesystem`	No	Shared filesystem for Ray data. Set `provision: false` to skip it.
`values.inference.domain`	Yes	DNS suffix for inference (`hostname.domain`). `hostname_template` is the host part only.
`values.gateway_api`	No	After provision, install Gateway API CRDs and a Cilium Gateway (`enable: true` by default).
`registration`	No	Same optional keys as Advanced flags (`storage_prefix`, `install_storage`, `ingress_class_name`, `ray_data_pvc_size`, and so on). Used by `register --spec` and `provision --register-and-install`.

generate-spec also comments out registration and some IDs so you can paste them in. Flags on provision and register override the YAML when both are set.