> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zylon.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Install Zylon (Legacy)

> A guide to install Zylon on a single instance

<Warning>
  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](/en/operator-manual/installation/index).
</Warning>

## 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](/en/operator-manual/installation/semi-airgap).
* 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

```bash theme={null}
# 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

```yaml theme={null}
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:

```bash theme={null}
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:

```yaml theme={null}
# 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-48g"

# 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 →](http://localhost:3090/en/operator-manual/configuration/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`                                                                        |

<Tip>
  For detailed Zylon instance configuration, refer to the [Configuration](/en/operator-manual/configuration/index) page.
</Tip>

## 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.

```bash theme={null}
sudo zylon-cli setup
```

This is what will be installed:

* Some common packages like gcc and git
* An embedded kubernetes distribution, [k0s](https://k0sproject.io/)
* [Nvidia drivers and CUDA ](https://developer.nvidia.com/cuda-downloads)
* [Nvidia Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/index.html)
* 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.

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

<Danger>
  **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](/en/operator-manual/troubleshooting/nvidia-drivers)
</Danger>

## 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.yaml`is correct.

```bash theme={null}
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.

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

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.

```bash theme={null}
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
```

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

## 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 [`name@company.com`](mailto: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.

```bash theme={null}
# 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.
```

<Danger>
  **Running the seed command will WIPE ALL DATA. Only do this once during the Zylon lifecycle**
</Danger>

The credentials to login to Zylon will be:

```bash theme={null}
user: admin@zylon.ai
password: the_password_you_set_up_previously
```

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`

```yaml theme={null}
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:

```bash theme={null}
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.

```bash theme={null}

# 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.

```bash theme={null}
sudo zylon-cli sync
```

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