Skip to main content
This guide covers the standard Zylon installation for environments with full internet access. The system will automatically download all required dependencies, container images, and AI models. Prerequisites Checklist:
  • Clean Linux machine (Ubuntu 22/24) meeting hardware requirements
  • Root and SSH access to the machine
  • A domain name for Zylon (e.g., zylon.company.com)
  • Ability to reboot the machine when needed
  • Machine has curl installed
  • Full, unrestricted internet access on the target machine
  • Firewall allows outbound connections to Docker registries and package repositories
  • Either:
    • Port 80 and 443 open for Let’s Encrypt automatic SSL certificate generation, OR
    • Valid SSL certificate ready for manual configuration

​
Installing Zylon

1

Install Zylon CLI

Estimated time: 2 minThe Zylon CLI will speed up the time it takes to get everything ready, it will take care of installing drivers, updating Zylon and configuring the system. To install it, SSH into the machine where you want to install Zylon and run:
# ssh <user>@<host-ip>
sudo curl -sL get.zylon.ai | sh
Verify the installation:
sudo zylon-cli version
Root access is required for CLI operations as it manages system-level dependencies and configurations.
2

Verify Zylon minimum requirements

Ensure your machine meets the hardware requirements for Zylon.To validate automatically if your installation meets the minimum requirements, run:
sudo zylon-cli preflight --network --fresh-system -v
Address any issues reported before proceeding with the installation. You will not be able to continue until all preflight checks pass.
Are you having issues with network connectivity? Consider moving to a Semi-Airgap Installation or Airgap Installation.
Zylon requires all checks to pass before providing installation support.
3

Configure Zylon

Estimated time: 10minZylon is configured using a YAML file located at /etc/zylon/zylon-conf.yaml.Generate Initial ConfigurationUse the CLI to generate an initial configuration file:
sudo zylon-cli config init
This opens an interactive prompt to guide you through configuration options.
If for any reason you got stuck during the interactive prompt, you can skip it by adding the -y flag to auto-generate a default configuration:
sudo zylon-cli config init -y
You will need to manually edit /etc/zylon/zylon-conf.yaml afterward to set your desired configuration based on the manual configuration section.
If you executed sudo zylon-cli config init, all configuration is set. Review /etc/zylon/zylon-conf.yaml to confirm settings. You can know more information about which settings are required in Manual Configuration section.
If you need to re-run the configuration wizard, execute:
sudo zylon-cli config init --force
You can
View Current Configuration
sudo cat /etc/zylon/zylon-conf.yaml
You can edit the configuration file directly using your preferred text editor (e.g., nano, vim):
# Choose one of the following commands:
sudo nano /etc/zylon/zylon-conf.yaml
sudo vim /etc/zylon/zylon-conf.yaml
For detailed information about all available configuration options, see the Configuration Guide.
4

Install Zylon

Estimated time: 15min to 1hour, depending on system performance and network speed.Run the installation command with your desired version:
sudo zylon-cli list-versions
# Choose your desired version from the list
sudo zylon-cli install <version>
Replace <version> with your target version (e.g., 1.50.0).What Gets InstalledThe installation process handles:
  • System dependencies (gcc, git, etc.)
  • Kubernetes distribution (k0s)
  • NVIDIA drivers and CUDA (if applicable)
  • Container runtime and tools (kubectl, helm)
  • Zylon container images
  • AI models from your configuration
  • SSL certificate generation (if using Let’s Encrypt)
5

Create Organization

Estimated time: 5 minAfter Zylon is installed and running, create your organization and root administrator account.Prepare InformationYou’ll need:
  • Organization name: Your company or team name (can be changed later)
  • Admin password: Secure password for root administrator (can be changed later)
    • Use alphanumeric characters due to encoding limitations with special symbols
  • Email regex: Pattern to auto-allow users to join
    • For name@company.com emails, use: .*@company\.com
    • For SSO (Microsoft Entra, Google), you can use: .*
Run Seed Command
sudo zylon-cli seed \
  --org-name "My Organization" \
  --admin-password "secure-password" \
  --email-regex ".*@yourcompany\.com"
The command will wait if Zylon is not fully ready.
Running the seed command will WIPE ALL DATA. Only run this once during the initial Zylon setup.
Login CredentialsAfter seeding, use these credentials to log in:
Username: admin@zylon.ai
Password: [the password you set]
The root admin email is always admin@zylon.ai and cannot be changed.
After first login, you can create additional administrators and configure SSO authentication.
6

Configure SSL (Optional)

Estimated time: 10 min
Skip this step if using Let’s Encrypt automatic certificates (default for public-facing instances).
For VPN or private cloud deployments, you need to manually install SSL certificates.Remove Automatic Certificate GenerationEdit /etc/zylon/zylon-conf.yaml and remove these lines:
certManagerAnnotations:
  cert-manager.io/cluster-issuer: "letsencrypt-prod"
Prepare Certificate FilesKubernetes requires the certificate split into two files:
  • tls.crt - The certificate file
  • tls.key - The private key file
Convert from PFX (if applicable):If you have a .pfx file, convert it:
openssl pkcs12 -in <your-certificate.pfx> -clcerts -nokeys -out tls.crt
openssl pkcs12 -in <your-certificate.pfx> -nocerts -out tls.key
Import Certificate into Kubernetes
# Remove any existing certificate
sudo k0s kubectl delete secret tls zylon-tls --ignore-not-found -n zylon

# Import your certificate
sudo k0s kubectl create secret tls zylon-tls \
  --key tls.key \
  --cert tls.crt \
  -n zylon

# Verify creation
sudo k0s kubectl describe secret zylon-tls -n zylon
Apply ChangesReload the Zylon configuration:
sudo zylon-cli sync
VerifyAccess your Zylon instance at https://zylon.your-company.com and confirm:
  • The connection uses HTTPS
  • The browser shows a valid certificate
  • No certificate warnings appear
Certificate renewal must be done manually by repeating this process with updated certificate files.

​
Updating Zylon

Updates follow the same process as installation: 
sudo zylon-cli list-versions
# Choose your desired version from the list
sudo zylon-cli install <new-version>
Alternatively, you can upgrade directly to the latest version using the upgrade command: 
sudo zylon-cli upgrade

​
Migrating to Online

If you have an existing Zylon installation (semi-airgap or airgap) and want to migrate it to a fully online environment, follow this guide. This process preserves your data, and configuration, while transitioning to online operation.
Migration differs from fresh installation:
  • Your existing configuration and data will be preserved
  • Organization and users already exist
To migrate an existing Zylon installation (Semi-Airgap, or Airgap) to an Online installation, follow these steps:
  1. Ensure connectivity: Verify that the target machine has full internet access.
  2. Update configuration: Run sudo zylon-cli config init --force to update the configuration for online operation.
  3. Refresh configuration: Execute sudo zylon-cli sync to apply the new configuration settings.
  4. Verify operation: Confirm that all services are functioning correctly with internet access.

​
Next Steps

After completing the installation, consider the following next steps to optimize your Zylon deployment: