Connect using the castctl CLI

castctl is the recommended way to connect Kubernetes clusters to Cast AI. It auto-detects your cloud provider, cluster name, and region from your kubeconfig, walks you through feature selection, and handles cluster registration, IAM setup, and the Helm install in a single command.

You can also connect clusters from the Cast AI console or with the Terraform provider.

What castctl supports

• Cloud providers: Amazon EKS, Google GKE, Microsoft AKS, and Cast AI Anywhere (on-premises, bare metal, and other clouds).
• Features: Cost Monitoring (always enabled), Node Autoscaling, and Workload Autoscaling.
• Karpenter: If Karpenter is already installed in the cluster, castctl offers to keep it as your node provisioner via Cast AI for Karpenter.

📘

Plan requirements

Node Autoscaling and Workload Autoscaling are Premium features. Cost Monitoring is available on every plan.

Before you start

Before you connect a cluster with castctl, make sure you have:

• A Cast AI account (sign up).
• A Kubernetes cluster on EKS, GKE, AKS, or a Cast AI Anywhere supported environment.
• kubectl configured for that cluster with admin access (kubectl auth can-i '*' '*').
• Cloud-side permissions equivalent to the console connection script's least-privileged policy — see Cloud permissions.
• metrics-server installed in the cluster, if you plan to enable Workload Autoscaling.

castctl bundles its own Helm logic, so you do not need helm, jq, or yq installed locally.

Install castctl

brew tap castai/tap
brew trust --cask castai/tap/castctl
brew install castctl

brew update && brew upgrade castctl

curl -fsSL https://get.cast.ai/linux | bash

# Install to /usr/local/bin
curl -fsSL https://get.cast.ai/linux \
  | bash

iwr -useb https://get.cast.ai/windows | iex

Verify the installation:

castctl version

Log in

Authenticate castctl with Cast AI using your browser:

1. Run the login command:

   Shell

   castctl auth login

2. castctl opens your default browser and asks to sign in to your Cast AI account.

3. After authentication, control returns to your terminal. If you belong to more than one organization, pick one from the interactive list. If you belong to a single organization, it's selected automatically.

4. castctl saves your token and organization ID to ~/.config/castctl/config.yaml and prints a confirmation message.

📘

Switching account or organization

Run castctl auth login again — it overwrites the stored credentials.

Connect your cluster

1. Start the interactive connection:

   Shell

   castctl cluster connect

   castctl detects the cloud provider, cluster name, and region from your kubeconfig and node labels, then prints the resolved configuration for you to review.

2. Select the features you want to enable.

3. Confirm the Proceed with connecting? prompt. castctl then:

   1. Registers the cluster with Cast AI.
   2. Installs the castai Helm chart in the castai-agent namespace.
   3. Creates the IAM resources required in your cloud account (AWS / GCP / Azure).

4. On success, castctl prints the cluster's Cast AI console URL. Open it to verify everything is connected.

Preview without making changes

Resolve the configuration and print it as YAML without registering the cluster or modifying anything:

castctl cluster connect --dry-run

Useful for validating that auto-detection picked the right provider, region, and cluster name.

Non-interactive mode (CI/scripts)

In CI pipelines or scripts, disable prompts with --non-interactive. The process can be customized using flags passed to the binary.

castctl cluster connect \
  --non-interactive \
  --cluster-optimization=false \
  --workload-autoscaler=true

For the complete list of flags supported by the current castctl — including feature toggles, GKE credential method, and Helm values overrides — run:

castctl cluster connect --help

Custom umbrella chart values

During cluster onboarding, castctl installs the Cast AI components using an umbrella Helm chart. You can customize the chart values (such as tolerations, node selectors, or resource limits) by providing a YAML values file with the --umbrella-values-file flag:

castctl cluster connect --umbrella-values-file /path/to/custom-values.yaml

This flag accepts a YAML file containing Helm values that are merged with the configuration castctl generates based on your feature selections. This approach provides flexibility to configure values that castctl doesn't explicitly manage through command-line flags.

Example custom-values.yaml:

global:
  tolerations:
    - key: "dedicated"
      operator: "Equal"
      value: "castai"
      effect: "NoSchedule"

For a complete reference of available values in the umbrella chart, see the castai-umbrella Helm chart documentation.

Connect a Cast AI Anywhere cluster

For clusters running outside EKS, GKE, or AKS — such as on-premises, bare metal, or other cloud providers — use the --provider anywhere flag:

castctl cluster connect --provider anywhere

Click here to learn more about Cast AI Anywhere.

Migrate from standalone Helm charts

If your cluster was previously connected using individual Cast AI Helm releases (one chart per component), castctl cluster migrate consolidates them into the unified umbrella chart. This preserves your cluster's Cast AI ID, carries forward any custom Helm values you supplied, and installs only the components that were already running.

The command also handles clusters where the Cast AI agent was installed via raw kubectl apply rather than Helm.

The castai-agent namespace and any non-chart-owned resources (including the castai-agent-metadata ConfigMap that holds the cluster ID) are not deleted.

⚠️

Brief downtime during migration

The migration uninstalls all standalone Helm releases before installing the umbrella chart. Cast AI components are absent from the cluster during this window. Node Autoscaling and Workload Autoscaling are paused until the umbrella chart install completes.

Run the migration

1. Switch your kubeconfig to the cluster you want to migrate.

2. Run:

   Shell

   castctl cluster migrate

   castctl reads the currently installed standalone releases, captures their values, uninstalls them, and then installs the umbrella chart with the reconstructed configuration.

3. Review the confirmation prompt and proceed. Use --yes to skip the prompt in scripts or CI.

4. On success, castctl confirms that all components are running under the unified chart.

Available flags

If the umbrella install fails

When the umbrella chart installation fails — for example, because an immutable field on an existing Deployment cannot be patched — castctl rolls back what it can and writes the captured standalone release values to a local file:

! Preserved standalone release values written to castai-migrate-values-20260730-083248.yaml
  Pass this file to `castctl cluster migrate --values-file <path>` or
  `helm upgrade castai castai/castai -f <path>` to reapply the custom configuration.

A debug snapshot ZIP is also saved to help diagnose the failure.

Fix the underlying issue (for example, delete the conflicting Deployment and let Helm recreate it), then pass the saved values file to retry. In --values-file mode, castctl skips standalone detection and uninstall entirely — only the umbrella chart installation runs:

castctl cluster migrate --values-file castai-migrate-values-20260730-083248.yaml

Alternatively, apply the values directly with Helm:

helm upgrade castai castai/castai -f castai-migrate-values-20260730-083248.yaml

The dump file contains a top-level releases: map with per-release values and the cluster ID, so both approaches restore the original configuration.

Disconnect a cluster

⚠️

This removes Cast AI completely

castctl cluster disconnect performs the equivalent of both Disconnect cluster and Remove cluster in the Cast AI console: it uninstalls the Cast AI Helm releases, deletes the IAM resources created during the connection, and removes the cluster record from Cast AI.

🚧

Not for Terraform-managed clusters

Do not run castctl cluster disconnect against a cluster that was connected with the Cast AI Terraform provider. The CLI does not coordinate with Terraform state and will leave your Terraform configuration out of sync. For Terraform-managed clusters, run terraform destroy instead — see Disconnect your cluster.

Clusters connected via the Cast AI console or castctl are supported.

1. Switch your kubeconfig to the cluster you want to disconnect.

2. Run the disconnect command:

   Shell

   castctl cluster disconnect

   castctl reads the Cast AI cluster ID from the in-cluster configuration, so you usually do not need to provide it.

3. Review the summary box. castctl prints every cloud resource it removed, any resources that were already absent, and any warnings to follow up on.

If a step fails, castctl prints a failure box noting which step failed and which cloud resources were already cleaned up. Fix the underlying issue and re-run the command — partial progress is preserved.

For the full list of disconnect options (including flags to skip cloud cleanup or the Kubernetes uninstall), run:

castctl cluster disconnect --help

See also