Skip to main content

​
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.
  • 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 [email protected]
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: "[email protected]" # 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-24g"

# 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:
ParameterSet to…Options
node.distroYour OS versionubuntu22, ubuntu24
node.archYour CPU architecturex86_64, arm64
node.driversYour hardware typegeneric
cluster.typek0sOnly k0s supported
channelstablestable (recommended), unstable
license.emailYour registered emailProvided during registration
license.idYour license keyReceived from Zylon team via email
ai.presetYour hardware capacitySee AI Presets →
companyIdentifierYour company namee.g., acme-corp
ingress.hostYour domaine.g., zylon.company.com
ingress.enabledtrueMust 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: 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)
  • A password for the root administrator (can be changed later).
    • Due to some encoding limitations in the CLI some special symbols in password don’t work correctly, prefer using a long alphanumeric password.
  • An email regex to allow users to join automatically. If your usual work email is [email protected] 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.
# Put a secure password!
sudo zylon-cli seed --org-name "My Org" --admin-password "admin" --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
The credentials to login to Zylon will be: 
user: [email protected]
password: the_password_you_set_up_previously
The root admin email is fixed and will always be [email protected] . 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.