This is the end-to-end walkthrough for a first-time online installation. For an air-gapped installation, see Offline (Air-Gapped) Installation.
Launching vamctl
- On the installer host, run
vamctl-<version>-win-x64.exefrom your Vizrt distribution as Administrator. This guide calls itvamctl.exe. Keep the file on the installer host for later upgrades. - A console window opens briefly, then your default browser launches and shows the installer at
http://127.0.0.1:<port>/. - The installer shows its terms and conditions first. Select I have read and accept these terms and conditions and click Accept and continue. The wizard then opens on its first step, Prepare Installer.
The installer hosts its own local web server on a loopback port. Leave the console window open for the duration of the install. If you close it, the wizard disconnects.
If the browser does not open automatically, copy the URL from the console window into a browser manually.
The wizard tracks its own progress in the left sidebar, and the header shows the current step. The total number of steps depends on the workflow you choose: creating a new cluster adds the Cluster Setup sub-steps. This guide therefore refers to screens by name rather than number.
Prepare Installer
The first step runs an environment check. It verifies the host and then downloads and verifies the command-line tools the installer needs. The header shows overall progress and how many parameters are verified.
PowerShell Prerequisites covers the host itself: the AIStor license, the PowerShell version, administrator privileges and the installers already present on the machine.
Environment & Tooling verifies each tool in turn: Podman, govc, Kubectl, Kustomize, Helm, Talosctl, Kubectl krew, Aws, AIStor MC, Oras and Wget. Each row reports Completed, Running, or Pending.
Podman is the row most likely to fail, and every install needs it, see Prerequisites > Podman and WSL 2.
Wait until every row reports Completed, then click Next. If a row fails, use Open Logs at the bottom of the window to read the reason. For Podman failures see Troubleshooting the Installer > Podman: Machine Will Not Start.
Choose a Workflow
Select what you want to do. For a fresh installation, choose Installation.
Workflow | Use it to |
|---|---|
Installation | Run the full installation and deployment flow. The installer host needs internet access, because the packages are pulled from the Vizrt registry. |
Prepare Offline Bundle | Prepare and export the offline bundle. For air-gapped installations only. Contact Vizrt support first, see Offline (Air-Gapped) Installation. |
Offline Installation | Install from a prepared offline bundle, for air-gapped installations only. The card is unavailable until you run Prepare Offline Bundle. |
Backup & Restore | Back up or restore the object-storage data. The installer restores only the archives it made itself. |
Manage Existing Cluster | Inspect a cluster and open the Configuration Service. Upgrade the platform by redeploying the applications, and upgrade or reinstall Talos on the nodes. See Upgrading. |
Manage Cluster Contexts | Import or export |
Settings | View and change the installer's own settings, such as the Podman options, timeouts and ports. |
There is no uninstall workflow. See Uninstalling.
Click Next.
Registry Login
The installer pulls VAM container images and Helm packages from the Harbor registry, so it needs credentials for a Harbor robot account.
- In Harbor Username, type the robot account name, in the form robot$vam+installer.
- In Harbor Password, type the robot account token.
Verification starts automatically as soon as both fields are valid, so there is no separate button to press. Until then the panel reports Credentials required. When verification succeeds, click Next.
If verification fails, see Troubleshooting the Installer > Registry Access.
Cluster Setup
The Installation workflow always installs the current versions from the registry. There is no version-selection step.
Choose whether the installer builds a cluster or deploys onto one you already run.
Create New Cluster provisions a new Kubernetes cluster on this machine, or on a remote Hyper-V or VMware vSphere host. Under Infrastructure parameters:
- Provisioning target: the platform that hosts the nodes, for example Hyper-V.
- Cluster name: the name of the cluster context. If the name already exists, the wizard shows a Context reuse advisory: the existing cluster is re-provisioned with the same context, and its MAC addresses are reused so DHCP leases survive.
- Create VMs on a remote Hyper-V host: select this to provision on another host, type its name in Remote hostname, then click Test. The panel reports Host reachable when the connection succeeds.
Use Existing Cluster deploys to a cluster that is already running, using the local kubeconfig and talosconfig. Select the Cluster context to deploy into. Cluster provisioning is skipped and deployment continues directly with Helm. To import or export contexts first, go back to the workflow selection and run Manage Cluster Contexts.
For VMware vSphere, follow the dedicated VMware vSphere Deployment guide for the connection details and required vCenter permissions.
For an existing cluster, the cluster must be empty or dedicated to VAM because the installer does not share a namespace with unrelated workloads. See Existing Kubernetes Cluster for the full prerequisites and flow (storage, certificates, ingress, identity).
Cluster Config
Define the cluster shape. A Resource Forecast panel on the right shows the estimated memory overhead for the current configuration, so you can see the cost of a change as you make it.
Topology
In Deployment model, choose:
- Single-node: fastest path for evaluations.
- Multi-node: runs the workloads on dedicated worker nodes, with 3 control plane nodes that keep etcd available when one of them fails.
Node Sizing
- Control plane nodes and Worker nodes: how many of each. The installer creates 1, 3 or 5 control planes. A cluster with 3 or 5 control planes needs at least 2 workers, and a cluster without workers has 1 control plane. The wizard reports a layout it does not create below the fields and does not continue with it.
- CPU cores, Memory (MB), Total disk (GB): per control plane node.
- Worker CPU, Worker RAM (MB), Worker total disk (GB): per worker node.
- Object-storage drives per worker: shown with at least 2 workers. The default is 1. The hint below the fields shows the total drives and the default parity. With 2 or 3 workers and 1 drive each, a second hint says that the installer splits each drive into 2 volumes and that the data has no parity. Set 2 or more for parity.
- Enable dynamic memory (ballooning): leave cleared unless the host is memory-constrained.
The minimum and recommended totals, and how the installer divides each total into a system disk and object-storage drives, are in Prerequisites > How the Installer Splits Disk per Node.
Network
- Public virtual switch: the switch the nodes attach to.
- Control plane address: Static IP or DHCP.
- Subnet and Gateway: a gateway is required for static networking.
- Control plane private IP (start) and Worker private IP (start): the internal cluster network on the private virtual switch. When deploying more than one cluster on the same Hyper-V host, give each a distinct address in the same range so they do not collide.
- Hyper-V destination path: where the node disks are stored. It appears after you click Show advanced settings. Use Browse folders to pick it.
Per-Node Configuration
The per-node cards appear after you click Show advanced settings. Each node appears as a card showing its role, hostname, MAC mode and assigned address. Expand a card to set the MAC mode for that node, and to assign a GPU to a worker from the devices the installer found on the host. For static networking, assign one IP per node.
If a node's VM name or DNS record already exists, the wizard lists the conflict above the cards.
DNS and Time
After you click Show advanced settings, set DNS servers and Time servers for the cluster nodes.
Cluster Review
Confirm the cluster architecture and network parameters before initialization. Cluster Configuration summarizes the cluster name, setup mode, topology, infrastructure and the resources allocated to control planes and workers. Node identities lists each node with its hostname, MAC address, static IP, GPU and effective resources.
Read this screen carefully. Changing the topology after this step requires reinstalling the cluster.
Further down, Network Architecture shows the address type, subnet, gateway, DNS resolvers and time servers. Pre-install checks lists any warnings, for example a planned private IP that is already used by a VM belonging to another cluster, which you must resolve on the Cluster Config step. If VMs from a previous install exist, Existing deployment will be overwritten names each one that is re-provisioned.
Select I have verified hostnames and MAC addresses and want to proceed, then click Next.
Cluster Install
The installer:
- Provisions the node VMs (or boots existing nodes with Talos).
- Installs Kubernetes.
- Joins worker nodes to the control plane.
- Verifies that the cluster is healthy.
Progress is shown step-by-step with live log output. If a step fails, the wizard moves on to Cluster Install Summary, which reports the failure. Read the reason with Open Logs, then click Retry there to run the installation again.
This typically takes 10 to 25 minutes for a single-node install and longer for multi-node. Do not close the wizard window during this step.
If the target host already has VMs from a previous install, the wizard pauses and asks you to confirm that they may be deleted and re-provisioned. Nothing is removed until you click Confirm.
Cluster Install Summary
When installation finishes, the wizard shows a summary of the installation steps and their results. If a step failed, read the reason with Open Logs and click Retry to run the installation again.
The cluster context is also written to your kubeconfig at this point, so you can inspect the cluster with kubectl from the installer host.
Click Download ZIP to save the cluster context bundle, which holds the kubeconfig and talosconfig of the new cluster. Store it as a secret. The step cannot be left until you download it. Then click Continue to Deployment Configuration.
Deployment Configuration
This step has the views Infrastructure and Deployment Options, shown at the top of the page.
View 1: Infrastructure
Prepare the cluster infrastructure: choose the deployment namespace, configure DirectPV storage and deploy any missing GPU support packages.
- Deployment namespace: the namespace for the main VAM deployment. Once infrastructure setup has started the namespace is locked, and the field explains why.
- Storage Configuration: shown only when the cluster uses DirectPV, which needs at least 2 workers with object-storage drives. A single-node cluster stores objects on the node disk instead and skips this panel. Apply Configuration stays unavailable while the selected drives cannot form a valid object store, and the panel says why. With 2 or 3 workers and 1 drive each, the summary shows 2 volumes on each drive. DirectPV is installed with the platform, but its drives are not initialized yet. The Recommended Configuration panel proposes a layout from the drives it finds and reports usable capacity, raw capacity, storage efficiency and how many drive and node failures the layout survives. Read the warnings before accepting: they call out HDD-only drives, drives with an existing filesystem that are formatted and single-node layouts that have no node-failure redundancy.
- AIStor Object Storage Configuration: derived from the same drives: servers, volumes per server, disk size and the erasure coding level.
- GPU Infrastructure: lists detected vendors and the required, installed and missing GPU packages. Use Refresh Status after installing one.
On first entry the panel discovers the drives on the cluster nodes. Use Discover Drives if it has not started, or Refresh Drives to re-scan later.
When discovery finishes, the Recommended Configuration panel appears. Review it, then click Apply Recommended Config to accept the layout.
Applying a configuration formats any selected drive that already has a filesystem. Confirm the drive list before you apply it.
Click Continue to Deployment Options.
View 2: Deployment Options
Review cluster defaults, security, certificates, package versions and optional deployment behavior. The banner at the top reports whether the configuration is valid and ready.
Upgrade existing installation appears when the cluster already has a VAM installation, and it is clear by default. With it clear, the deployment uninstalls the existing VAM releases and deletes their data, including the stored assets, before it installs from scratch.
- Cluster Details: the installer loads the existing deployment configuration from the selected cluster. Use Refresh from Cluster to reload it. Select Upgrade existing installation to keep the currently installed releases and existing cluster resources in place.
- Backup & Restore: optionally select Backup AIStor data before deployment (useful for a fresh install onto a cluster that already holds data), and optionally Restore from backup after deployment.
- Global Configuration: the FQDN clients use to reach the platform, and the Storage Class for persistent volumes. The installer proposes the first control plane's name in the DNS domain of the machine that runs the installer. The name you leave here is the one the gateway certificate, the routes and the sign-in redirect carry, so enter the fully qualified name clients will use, not a short host name. The name applies to this deployment only. The next deployment starts from the proposal again.
- Authorization: the identity provider. Set Security to External OIDC (recommended) and enter the provider and its OIDC host URL, the Directory (tenant) ID in OIDC App ID (tenant), the client ID, client secret and shared client ID. Take these values from Identity Provider Setup > Values for the Installer. Microsoft Entra ID is the only officially supported identity provider. The other options are not officially supported and are experimental.
- License: in License servers, the hostname or IP address of the CodeMeter license server. See Prerequisites > Licensing.
- cert-manager (ADCS): to have Active Directory Certificate Services (ADCS) issue the certificates, fill in ADCS web service URL, Certificate template (the name of the template to request against), CA Bundle (the root and intermediate chain), Root certificate path (the root certificate file, or use Pick certificate file), and the Username and Password of an account that may enroll certificates from that template. Leave them empty to use the installer's built-in certificate authority. The template must meet the requirements in Prerequisites > Certificate Template for ADCS.
- Platform applications: VAM and the Configuration Service are always installed. Every other application is installed later from the Configuration Service.
- Infrastructure & Platform Dependencies: the packages that are included automatically and deployed in the correct order, with their versions. Infrastructure packages (cert-manager, Traefik, storage) are always required.
The selector above the application list switches between the Registry (production) and Development registries. Development builds are unstable and are not intended for production installations. Point the installer at the production registry before installing a live environment.
Click Start Deployment.
Deploy
The installer deploys VAM to the cluster with Helm. The header shows overall progress and the done / running / pending counts. The Deployment steps list expands into the individual releases.
The stages are: preparing the cluster context, validating Kubernetes connectivity, a pre-flight dry-run validation, infrastructure (Traefik, cert-manager, storage, secrets), platform services (SurrealDB, AIStor, RabbitMQ, OpenTelemetry), the applications themselves and finally the ingress routes.
This can take 15 to 30 minutes depending on your registry bandwidth and node hardware. When it reports Helm deployment completed successfully, click Run Sanity Check.
Sanity Check
The System Health Check groups its results into Connectivity, Kubernetes, Packages and Services and reports how many checks pass out of the total. Expand a category to see the individual checks.
- When all checks pass, click Next to finish.
- When a category fails, expand it to read the diagnosis, fix the cause, then click Run Checks to test again.
Finish
Workflow Complete confirms that every step succeeded and the environment is ready.
The platform, VAM and the Configuration Service are installed. Every other application is installed and managed from the Configuration Service, so the next step is to open it: click Open Configuration Service, which opens the URL shown beneath the button (the FQDN you set, on port 30443, at /config) in a new tab.
The Summary section records the workflow that ran, the cluster and its topology, the packages installed and the result.
Use Open Logs to read the install log, and Back to Workflow Selection to run another workflow, such as a backup. For a support case, attach the log file from %APPDATA%\Vizrt\vamctl\logs\.
Next Steps
- Post-Install Validation: recommended checks before you hand the installation over to users.
- Signing In: first login walkthrough.
Resuming an Interrupted Install
If the browser tab was closed while the installer kept running, open the installer URL from the console window again. The wizard returns to the step you were on. If a long-running operation, such as a cluster installation or a deployment, is still in progress, the wizard reconnects to the running operation rather than restart it.
The wizard keeps its progress only while the installer runs. If the installer was closed or the host rebooted, launch vamctl.exe again and start the workflow again.


















