Skip to main content
Version: main 🚧

Standalone Quick Start

You want to run a managed Kubernetes platform on your own infrastructure, similar to EKS or GKE. You don't have an existing Kubernetes cluster to build on. You might be a GPU cloud provider, a neocloud, or an enterprise with bare metal to put to work.

The first problem is always the same. To run vCluster, you need a Kubernetes cluster. But getting a Kubernetes cluster onto bare metal normally requires another tool first. vCluster Standalone breaks this loop. It installs a complete Kubernetes control plane directly on a Linux machine as a binary, with no existing distribution required.

This guide takes you from a bare Linux machine to a running Control Plane Cluster with vCluster Platform installed on it. Once Platform is running, you can provision tenant clusters with dedicated private nodes in seconds. That's the path GPU clouds and neoclouds use to deliver hyperscaler-grade isolation to their customers.

Prerequisites​

  • A Linux machine (bare metal or VM) meeting the node requirements
    • Ubuntu 22.04 or 24.04 recommended
    • Root access required
    • Outbound internet access for image pulls
  • The machine must be reachable from your local workstation (SSH access)

Install the vCluster CLI​

brew install loft-sh/tap/vcluster

The binaries in the tap are signed using the Sigstore framework for enhanced security.

Verify the CLI installed successfully.

vcluster --version

Output is similar to:

vCluster version 0.x.x

Install vCluster Standalone​

Run these commands on the control plane machine as root.

  1. Set the version and config directory.

    export VCLUSTER_VERSION=v0.33.1
    export CONFIG_DIRECTORY=/etc/vcluster
    mkdir -p $CONFIG_DIRECTORY

  2. Create a minimal vcluster.yaml configuration.

    cat <<EOF > $CONFIG_DIRECTORY/vcluster.yaml
    controlPlane:
      distro:
        k8s:
          version: v1.35.0
    EOF

  3. Run the installer.

    sudo su -
    curl -sfL https://github.com/loft-sh/vcluster/releases/download/${VCLUSTER_VERSION}/install-standalone.sh \
      | sh -s -- --vcluster-name standalone

    The installer downloads Kubernetes binaries, configures the control plane, and writes a kubeconfig to /var/lib/vcluster/kubeconfig.yaml. Installation takes about 2 minutes.

  4. Verify the control plane node is ready.

    kubectl get nodes

    Output is similar to:

    NAME               STATUS   ROLES                  AGE   VERSION
    ip-192-168-3-131   Ready    control-plane,master   2m    v1.35.0

Your machine is now a single-node Kubernetes cluster. This is the Control Plane Cluster. Worker nodes join separately as private nodes when you provision tenant clusters.

Access the cluster from your workstation​

The kubeconfig is written to /var/lib/vcluster/kubeconfig.yaml on the control plane node. Copy it to your local machine and update the server address.

# On the control plane node — print the kubeconfig
cat /var/lib/vcluster/kubeconfig.yaml

Copy the output to ~/.kube/config on your workstation. Replace the server: value with the machine's public IP or DNS name:

server: https://<YOUR_MACHINE_IP>:6443

Verify access from your workstation:

kubectl get nodes

Install vCluster Platform​

With the Control Plane Cluster running, install vCluster Platform on it. Platform is free to use and provides tenant cluster provisioning, access controls, auto-sleep, and node automation.

vcluster platform start

This installs Platform into the vcluster-platform namespace. When complete, the CLI prints your login credentials and a URL:

##########################   LOGIN   ############################

Username: admin
Password: <generated-password>

Login via UI:  https://<subdomain>.loft.host
Login via CLI: vcluster platform login https://<subdomain>.loft.host

#################################################################

The UI opens automatically. Create your administrator account and you are logged in.

What you have now​

  • A bare-metal or VM-based Kubernetes cluster running as a vCluster Standalone instance
  • vCluster Platform installed and running on it
  • A foundation for provisioning tenant clusters with private nodes

Next steps​