Install Zylon (Legacy)

This guide only applies to Zylon 1.53.0 or earlier. For newer versions, the installation process is different and you should refer to the main installation guide.

Prerequisites

For a smooth sailing make sure you pass this checklist before you begin the installation:

The target machine is clean of any other software that can interfere with it. That means no docker, no kubernetes, http servers, no Nvidia drivers, etc.
You have root and SSH access to the machine
The machine has stable and strong Internet connection
You can reboot the machine if needed
Your firewall is not blocking connections to any website.
- In case you run in a restricted environment, check the semi-airgap instructions.
The machine has curl installed
You have a domain for Zylon ready (ex: zylon.your-company.com)
- If your instance is not open to the internet you have a valid SSL certificate for that domain, it will be needed as the last step of the installation.

Once you have fulfilled the hardware requirements and have a domain ready it is time to install Zylon! For single instance setups Zylon it’s installed using it’s CLI zylon-cli on the machine where you want to run it. To start the install process make sure that:

At install time, the machine has internet connection (After Zylon has been installed internet connection it is not a requirement)
You have ssh access to the machine
Firewall rules will not block the CLI to download any Zylon container images or certificate generation

Step 1: Install the Zylon CLI

Estimated time: 2 min The CLI will speed up the time it takes to get everything ready, it will take care of installing drivers, updating Zylon and generating template configuration for you. To install it, SSH into the machine where you want to install Zylon and run

# ssh user@zylon.company.com
sudo curl -sL get.zylon.ai | sh

Root access is required at multiple steps into the installation, if you wish to inspect the script simply run

curl -sL get.zylon.ai

Run sudo zylon-cli help to get a list of all the commands!

Step 2: Generate a configuration file for your Zylon installation

Estimated time: 10min Zylon is configured with a YAML file located at /etc/zylon/zylon-conf.yaml. You can use the Zylon CLI to generate a configuration template:

sudo zylon-cli config

This outputs a template that you must populate with your specific values and save to /etc/zylon/zylon-conf.yaml. Note that you will need root access to edit this file. A basic configuration file will look like this:

# Machine configuration, this is the only supported option
node:
  distro: "ubuntu22" # or ubuntu24
  arch: "x86_64" 
  drivers: "generic" 

# Cluster type, this is the only
# supported option for single instance installations
cluster:
  type: "k0s"

# unstable channel also available under request
channel: "stable"

license:
  email: "champion@company.com" # The email asigned to the license
  id: "2oq..." # A license id a Zylon employee shared with you via email

# AI configuration, detailed information below.
ai:
  preset: "baseline-96g"

# We will use this to identify your company in our anonymous metrics
# You can set any identifier, if you have multiple installations
# make the identifier different, for example, company, and company-test
companyIdentifier: "your-company"

# Enable anonymous metrics and crash reporting
observability:
  crashReporting: true
  usageMetrics: true

# Your network configuration
ingress:
  host: "zylon.your-company.com" # The domain you have prepared for Zylon
  enabled: true
  tlsEnabled: true
  certManagerAnnotations:
    # If you plan to open the machine to the internet, SSL certificate
    # will be automatically generated using letsencrypt
    # Otherwise, check the SSL documentation to import a custom certificate
    cert-manager.io/cluster-issuer: "letsencrypt-prod"

Configuration Parameters

Fill in each required parameter using the values that match your environment:

Parameter	Set to…	Options
`node.distro`	Your OS version	`ubuntu22`, `ubuntu24`
`node.arch`	Your CPU architecture	`x86_64`, `arm64`
`node.drivers`	Your hardware type	`generic`
`cluster.type`	`k0s`	Only `k0s` supported
`channel`	`stable`	`stable` (recommended), `unstable`
`license.email`	Your registered email	Provided during registration
`license.id`	Your license key	Received from Zylon team via email
`ai.preset`	Your hardware capacity	See AI Presets →
`companyIdentifier`	Your company name	e.g., `acme-corp`
`ingress.host`	Your domain	e.g., `zylon.company.com`
`ingress.enabled`	`true`	Must be `true`

For detailed Zylon instance configuration, refer to the Configuration page.

Step 3: Prepare the machine

Estimated time: 5min to 45min, depending on network speed. In order to install Zylon the machine needs to be ready to do so, and during this step, the drivers will be installed, an embedded kubernetes cluster, and other dependencies will be setup. This process will take between 5 to 15 minutes, it’s normal to see the output freeze while some installers are running, simply wait until it’s done. In slow network conditions, this process might take up to 1 hour.

sudo zylon-cli setup

This is what will be installed:

Some common packages like gcc and git
An embedded kubernetes distribution, k0s
Nvidia drivers and CUDA
Nvidia Container Toolkit
Some tool utilities to manage the kubernetes cluster (kubectl, helm, helmfile…)

Generally, you only need to run the setup once. Running it multiple times has no effect unless an update by Zylon team adds a new dependency.

It’s highly recommended to reboot the machine after this step is completed to ensure GPU drivers are properly loaded.

Kernel upgrades (like Ubuntu unattended upgrades) will break Nvidia drivers on every change!.To test if the drivers are working use nvidia-smi utility, it will display the status of your GPU(s) or fail if the drivers are not working:An implicit kernel update might also happen after a restart of the machine when running in cloud providers like AWS or Azure.Check the following page for troubleshooting: Nvidia Drivers Troubleshooting

Step 4: Install Zylon

Estimated time: 15min to 1hour, depending on network speed. This step (install / update) will make Zylon available in your machine assuming the configuration file in /etc/zylon/zylon-conf.yamlis correct.

sudo zylon-cli update

To update Zylon to a newer version, simply run this command again. You can do so as frequently as you need. If you modify your Zylon configuration file you will also need to run the update command again.

The initial installation of Zylon will take around 15 minutes to complete after the update command itself is completed.

This is what is happening in the background:

Zylon images are being downloaded
AI models are being downloaded
GPU configuration is getting applied, several validations are running to ensure compatibility
SSL certificate is being generated

You can watch the process running. When all pods are at 1/1 ready status you can proceed.

watch sudo k0s kubectl get pods -n zylon
# You can also watch nvidia GPU validation process, more prone to failure
watch sudo k0s kubectl get pods -n nvidia

If some service gets stuck in a ContainerCrashLoopBackOff for more than one hour contact us, the installation has failed.

Step 5: Prepare your organization

To start using Zylon you will need to create your organization in it, as well as adding a root admin that will serve as your entry point for other management tasks. You will need:

A name for your organization (can be changed later)
An email regex to allow users to join automatically. If your usual work email is name@company.com your email regex should be .*@company\.com . If your access control is performed with SSO (like Microsoft Entra, or Google), you can use .* as your regular expression.

sudo zylon-cli seed --org-name "My Org" --email-regex ".*@yourcompany\.com"

# At seed time, if Zylon is not ready,
# this command will wait until it’s completed.

Running the seed command will WIPE ALL DATA. Only do this once during the Zylon lifecycle

After seeding, retrieve the one-time login password for the admin account:

sudo zylon-cli admin-password

The credentials to login to Zylon will be:

user: admin@zylon.ai
password: the_one_time_password_printed_above

The root admin email is fixed and will always be admin@zylon.ai . You will need to use these credentials to login for the first time in the workspace.

Step 6 (optional): Manually installing SSL certificates

Estimated time: 10 minutes If you opted in to use Let’s Encrypt certificates you can skip this section. In case your Zylon installation is behind a VPN / private cloud and it’s not reachable through the internet you will need to configure SSL yourself. To do that you must upload your own SSL certificates and make them available to the server where Zylon is installed.

Configuration file

First, REMOVE the following lines from the configuration file /etc/zylon/zylon-conf.yaml

certManagerAnnotations:
  cert-manager.io/cluster-issuer: "letsencrypt-prod"

Since we are using Kubernetes we need to have the private key (*.key ) and the certificate file in two files (*.crt ) to store them as a secret.

For .pfx file (ignore otherwise)

In case you have a .pfx file you can get the desired files with the following commands:

openssl pkcs12 -in <your-certificate.pfx> -clcerts -nokeys -out tls.crt
openssl pkcs12 -in <your-certificate.pfx> -nocerts -out tls.key

Create secret a secret in the kubernetes cluster

Clear previous certificates (if any) and import the new one. Zylon will look for your certificate in the cluster with the name zylon-tls. Note that kubernetes requires the certificate split in two files, the .crt with certificate itself and .key with the private key.

# Import or refresh the certificates
sudo k0s kubectl delete secret tls zylon-tls --ignore-not-found -n zylon
sudo k0s kubectl create secret tls zylon-tls --key tls.key --cert tls.crt -n zylon

# Check if it's correctly created
sudo k0s kubectl describe secret zylon-tls -n zylon

To reload the changes done to the configuration file, reload the configuration.

sudo zylon-cli sync

Finally, go to your Zylon instance and confirm that the connection is using HTTPS.

Getting Started

Installation

Maintenance & Operations

Backoffice

Configuration

Troubleshooting

Security

Auditability & AI Governance

Install Zylon (Legacy)

Prerequisites

Step 1: Install the Zylon CLI

Step 2: Generate a configuration file for your Zylon installation

Configuration Parameters

Step 3: Prepare the machine

Step 4: Install Zylon

Step 5: Prepare your organization

Step 6 (optional): Manually installing SSL certificates

Configuration file

For .pfx file (ignore otherwise)

Create secret a secret in the kubernetes cluster

​Prerequisites

​Step 1: Install the Zylon CLI

​Step 2: Generate a configuration file for your Zylon installation

​Configuration Parameters

​Step 3: Prepare the machine

​Step 4: Install Zylon

​Step 5: Prepare your organization

​Step 6 (optional): Manually installing SSL certificates

​Configuration file

​For .pfx file (ignore otherwise)

​Create secret a secret in the kubernetes cluster

Prerequisites

Step 1: Install the Zylon CLI

Step 2: Generate a configuration file for your Zylon installation

Configuration Parameters

Step 3: Prepare the machine

Step 4: Install Zylon

Step 5: Prepare your organization

Step 6 (optional): Manually installing SSL certificates

Configuration file

For .pfx file (ignore otherwise)

Create secret a secret in the kubernetes cluster