Semi-Airgap Installation

This guide covers Zylon installation for environments with limited internet access due to firewall restrictions or proxy requirements. The system requires one-time internet connectivity during installation and updates. 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

Proxy server configured with credentials (if required)
Network team has whitelisted required domains and ports (see Required Network Access)
Firewall rules allow connections through the proxy
Valid SSL certificate for your domain (Let’s Encrypt typically won’t work in restricted networks)

Required Network Access

Your firewall must allow access to these domains: Essential Services (Mandatory):

get.zylon.ai - CLI installation
zylon-cli.s3.us-east-1.amazonaws.com - CLI binaries and dependencies
zylon-artifacts.s3.us-east-1.amazonaws.com - Zylon installation files and updates

Public Container Registries:

quay.io - Third-party container images
ghcr.io - GitHub container registry
docker.io - Docker Hub images
registry.k8s.io - Kubernetes images
reg.kyverno.io - Kyverno policy engine
nvcr.io - NVIDIA Container Registry

Since Zylon required public open-source images, network access to original registries is required during installation and updates. If your security policies restrict access to public container registries, consider moving to an airgap installation using Zylon Airgap Installation Guide.

AI Models & Dependencies (Only applicable if you need custom AI models):

huggingface.co - AI model repository
xet.huggingface.co - Hugging Face XET protocol

License Validation (Only applicable if Replicated license is used):

replicated.app - Zylon distribution platform
api.replicated.com - License validation
proxy.replicated.com - Zylon container images

Installing Zylon

Install Zylon CLI

Estimated time: 2 min

Before starting the installation, validate that your machine can reach get.zylon.ai:

curl -sLv get.zylon.ai -m 3 | exit 1

If the connection is giving errors, work with your network team to resolve them. Once connectivity is verified, you can proceed.

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

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 an Airgap Installation.

Zylon requires all checks to pass before providing installation support.

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.

Auto Configuration
Manual Configuration

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

Edit /etc/zylon/zylon-conf.yaml to adjust settings as needed.Define your OS distributionSet node.distro to match your Ubuntu version:

node:
  distro: "ubuntu22"  # for Ubuntu 22.04
  # distro: "ubuntu24"  # for Ubuntu 24.04

Define your CPU architectureSet node.arch to match your hardware:

node:
  arch: "amd64"  # for Intel/AMD processors

Set your hardware drivers (if applicable)Set node.drivers to generic (this is the only supported option):

node:
  drivers: "generic"

Configure cluster typeSet cluster.type to k0s (this is the only supported option for single instance installations):

cluster:
  type: "k0s"

Select your release channelSet channel to stable (recommended for production and normal use) or unstable (available under request for testing):

channel: "stable"

Add your license informationSet license.email to the email address assigned to your license (provided during registration).Set license.id to the license ID shared with you by the Zylon team via email:

license:
  email: "champion@company.com"
  id: "2oq..."

Choose your AI presetSet ai.preset based on your available GPU memory. See AI Presets for details.

ai:
  preset: "baseline-24g"

Set your company identifierSet companyIdentifier to any identifier for anonymous metrics tracking (e.g., acme-corp). If you have multiple installations, use different identifiers (e.g., company and company-test):

companyIdentifier: "your-company"

Disable telemetry & crash reportingTo disable telemetry and crash reporting, add the following section:

observability:
    crashReporting: false
    usageMetrics: false

Configure network ingressSet ingress.host to the domain you’ve prepared for Zylon. This should be a fully qualified domain name (FQDN) that points to your server’s IP address.Examples:

zylon.company.com
ai.acme-corp.com
zylon-prod.yourcompany.io

ingress:
  host: "zylon.your-company.com"
  enabled: true
  tlsEnabled: true

Configure SSL certificate generationIf your server is accessible from the internet, Let’s Encrypt will automatically generate and renew SSL certificates. Keep the default certManagerAnnotations:

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

If you’re in a private network or need to use a custom certificate, see Disable Let’s Encrypt below.Local License (If Needed)If api.replicated.com is blocked during operation, you need a local license. Contact Zylon support to obtain it, then add:

license:
  email: "champion@company.com"
  id: "2xo..."
  type: "Zylon"
  data: |-
    [eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...]

Replace the data field with the actual license data provided by Zylon team. Please be careful with formatting and indentation. Just copy the token that starts with eyJ....

Proxy configuration (If Needed)Refer to the Proxy Configuration Guide to set up proxy settings in your configuration.Disable Let’s EncryptEdit /etc/zylon/zylon-conf.yaml and remove these lines:

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

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.

Install Zylon

Estimated time: 15min to 1hour, depending on system performance and network speed.Run the installation with your desired version:

sudo zylon-cli list-versions
# Choose your desired version from the list
sudo zylon-cli install <version>

The 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)

Installation may take 15-60 minutes depending on network speed and firewall restrictions.

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.

Configure Offline Operation

Estimated time: 5 minAfter validate that Zylon is running correctly, you can enable offline operation. This will configure Zylon to work without internet access. Edit /etc/zylon/zylon-conf.yaml and add:

airgap:
  offline_operation: true

And sync the configuration:

sudo zylon-cli sync

This will disable connectivity in AI, K8s and other subsystems.

Configure SSL (Optional)

Estimated time: 10 minFor VPN or private network 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

To update the instance, we will need to remove network restrictions temporarily on a connected machine to download update packages. Contact your network security team to whitelist the required domains during this process. After downloading, you can reapply the restrictions. Before you update, be sure to disable offline mode by editing /etc/zylon/zylon-conf.yaml and setting:

airgap:
  offline_operation: false

Validate if Zylon has connectivity again by running:

sudo zylon-cli preflight --network -v

If all checks pass, proceed to download and install the update:

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

When the process is complete, re-enable offline mode by setting:

airgap:
  offline_operation: true

Migrating to Semi-Airgap

If you have an existing Zylon installation (online or full-airgap) and want to migrate it to a semi airgapped environment, follow this guide. This process preserves your data, and configuration, while transitioning to offline operation.

Migration differs from fresh installation:

Your existing configuration and data will be preserved
SSL certificates will be migrated
Organization and users already exist

To migrate an existing Zylon installation (Online, or Airgap) to an Online installation, follow these steps:

Ensure connectivity: Verify that the target machine has connectivity with below domains.
Update configuration: Run sudo zylon-cli config init --force to update the configuration for online operation. Be sure to configure as Configure Zylon step describes.

Be sure to select Semi-Airgap when you run the configuration wizard.
If you don’t have connectivity with replicated domains, be sure to request a local license to Zylon support team.

Disable offline mode: Edit /etc/zylon/zylon-conf.yaml and set:
```
airgap:
  offline_operation: false
```
Refresh configuration: Execute sudo zylon-cli sync to apply the new configuration settings.
Verify operation: Confirm that all services are functioning correctly.

Next Steps

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

Configure AI Presets to optimize for your hardware
Configure Backups for data protection
Review User Manual to get started

Getting Started

Installation

Configuration

Maintenance & Operations

Troubleshooting

Semi-Airgap Installation

Required Network Access

Installing Zylon

Updating Zylon

Migrating to Semi-Airgap

Next Steps

Getting Started

Installation

Configuration

Maintenance & Operations

Troubleshooting

​Required Network Access

​Installing Zylon

​Updating Zylon

​Migrating to Semi-Airgap

​Next Steps

Required Network Access

Installing Zylon

Updating Zylon

Migrating to Semi-Airgap

Next Steps