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, and Microsoft AKS.
• 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, or AKS.
• 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 install castctl

brew upgrade castctl

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.

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

• Enable automation — what the connection installs in your cluster and cloud account.
• Hosted components — the Kubernetes workloads castctl deploys.
• Cloud permissions — the IAM resources castctl creates.
• Autoscaler checklist — recommended next steps after the cluster is connected.
• Connect using the Cast AI console — the console-based alternative.
• Disconnect your cluster — manual and Terraform-based disconnect flows.