Airgap installation enables Zylon deployment in environments with zero internet access. This process requires two separate Linux machines: one with internet connectivity for downloading bundles, and one offline machine for running Zylon.Prerequisites Checklist:
In your online machine, ensure firewall 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
These domains must be reachable from the online machine to download Zylon bundles and updates.
If direct internet access is not available, you can configure a proxy server.
Configuring Proxy Settings
Set the following environment variables before running any Zylon CLI commands:
Verify Proxy ConfigurationTest connectivity through the proxy before proceeding:
# Test HTTP connectivitycurl -v -x $HTTP_PROXY http://get.zylon.ai# Test HTTPS connectivity (if using self-signed cert)curl -v -x $HTTPS_PROXY --cacert $SSL_CERT_FILE https://get.zylon.ai
Running Commands with sudo⚠️ Important: The sudo command does not preserve environment variables by default. You must use the -E flag to pass proxy settings to commands requiring elevated privileges:
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.
2
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
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:
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:
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:
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:
If you’re in a private network or need to use a custom certificate, see Disable Let’s Encrypt below.Airgap SettingsEnsure these settings are included to indicate airgap installation and operation:
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... and ends with ....
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.yamlsudo vim /etc/zylon/zylon-conf.yaml
For detailed information about all available configuration options, see the Configuration Guide.
3
Download AI Models
Estimated time: 10min to 1h, depending on network speed and models.Before downloading Zylon, you must download the AI models on the online machine. The models are determined by your AI preset configuration.Check available models and compare with your AI preset:
sudo zylon-cli models list
More preset details in the AI Presets documentation.Download the models based on your configuration:
sudo zylon-cli models download --no-extract
This will download the AI models that you have specified in the Wizard.If for some reason you need to download specific models, you can do so with:
Estimated time: 5 to 30 min, depending on models size.After downloading the models, export them for transfer to the offline machine:
sudo zylon-cli models export
This creates a zylon-models-<timestamp>.tar file in your current directory containing all selected AI models.
The model export file can be 10-100 GB depending on which models you have downloaded.
5
Download Zylon Bundle
Estimated time: 15min to 2h, depending on network speed.Download the specific Zylon version you want to install:
sudo zylon-cli list-versions# Choose your desired version from the listsudo zylon-cli download <version> --airgap
Replace <version> with your target version (e.g., 1.50.0).
Note that we do not use the --models flag here since models were already handled in the previous steps.
6
Export Bundle
Estimated time: 15 to 60 min, depending on version.Export the downloaded version into an airgap bundle:
sudo zylon-cli export <version>
This creates zylon-<version>-<os>-<arch>.tar in your current directory. Additionally, it will generate
the commands to run on the offline machine for installation to import and install Zylon. Store these commands safely.
Export can take significant time. The resulting tar file may be 60-80GB.
7
Prepare Initial Transfer (First Install Only)
First installation only! After initial setup, the CLI self-updates from airgap bundles.
Create a bundle with CLI tools and configuration:
sudo tar -czf zylon-initial.tar.gz \ /usr/local/bin/zylon-cli \ /usr/local/bin/zylon-forge-cli \ /etc/zylon/zylon-conf.yaml
8
Prepare Certificates (Optional)
Estimated time: 5 minIf your Zylon instance is in a private network or VPN, you need to manually provide SSL certificates.
Prepare them for transfer:Gather your SSL certificate files:
crt.pem (Certificate + Intermediate)
key.pem (Private Key)
Create a tarball for transfer:
sudo tar -czf zylon-ssl-certs.tar.gz crt.pem key.pem
9
Transfer Files
Transfer files to the offline machine using your preferred method (SCP, USB, external drive):First installation:
zylon-<version>-<os>-<arch>.tar (main bundle)
zylon-models-<timestamp>.tar (AI models)
zylon-initial.tar.gz (CLI and config)
zylon-ssl-certs.tar.gz (SSL certs, if applicable)
Subsequent updates:
zylon-<version>-<os>-<arch>.tar (main bundle)
zylon-models-<timestamp>.tar (AI models export, if adding new models)
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.aiPassword: [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.
7
Configure SSL Certificates (If applicable)
Estimated time: 10 minIf you prepared SSL certificates on the online machine, extract them now:
cd /tmpsudo tar -xzf zylon-ssl-certs.tar.gz -C /tmp/ls /tmp/crt.pem /tmp/key.pem
If you see both files, proceed to install them as follows:Remove Automatic Certificate GenerationEdit /etc/zylon/zylon-conf.yaml and remove these lines:
Updates in airgap environments follow a similar two-machine workflow. The process is faster than initial installation since you’re only transferring changes, not the entire platform.
Estimated Time: 45-60 minutes total (15-20 min online machine, 25-40 min offline machine)
1
On Online Machine: Download New Models (If Needed)
Estimated time: 10 to 60 min (only if adding new models)Skip this step if you’re not adding new AI models.If you’re changing AI presets, upgrading GPU requirements, or need additional models:First, check your current and available models:
If you have an existing Zylon installation (online or semi-airgap) and want to migrate it to a fully airgapped environment, follow this guide. This process preserves your data, configuration, and SSL certificates 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
Migration Prerequisites:
Existing Zylon installation (online or semi-airgap) with access
Online machine with internet access for downloading migration bundles
Method to transfer files (70-100 GB) between machines
If the certificate extraction fails, it means you’re using Let’s Encrypt auto-generation. In this case, you’ll need to provide your own certificates or continue using Let’s Encrypt on the airgap machine (not recommended for airgap environments).
3
Transfer Files to Online Machine
Transfer the configuration and certificates to your online machine:SCP Example:
# From existing Zylon machine to online machinescp /tmp/zylon-conf-backup.yaml user@online-machine:/tmp/scp /tmp/tls.crt user@online-machine:/tmp/scp /tmp/tls.key user@online-machine:/tmp/
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
Transfer Configuration File
Estimated time: 2 minPlace the backed-up configuration in the correct location: