Skip to main content
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:
  • 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
  • Online machine with internet access to download installation bundles
  • Method to transfer files (70-100 GB) to the isolated target machine (USB drive, internal network, etc.)
  • Target machine has NO internet connection
  • Valid SSL certificate for your domain
  • Sufficient storage on online machine and transfer media for large bundles

Required Network Access

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.
Set the following environment variables before running any Zylon CLI commands:
Using Self-Signed CertificatesIf your proxy uses a self-signed certificate, you must also configure the CA certificate:
Verify Proxy ConfigurationTest connectivity through the proxy before proceeding:
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:

Installing Zylon

1

Online Machine

Download Zylon bundles and AI models with internet access
2

Transfer

Move bundle files to offline machine via secure transfer method
3

Offline Machine

Import and install Zylon without any internet connectivity

Part A: Online Machine Setup

1

Install CLI

Estimated time: 2 min
Before starting the installation, validate that your machine can reach get.zylon.ai:
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:
Verify the installation:
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:
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:
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:
View Current Configuration
You can edit the configuration file directly using your preferred text editor (e.g., nano, vim):
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:
More preset details in the AI Presets documentation.Download the models based on your configuration:
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:
For example, for baseline-96g preset:
4

Export AI Models

Estimated time: 5 to 30 min, depending on models size.After downloading the models, export them for transfer to the offline machine:
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:
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:
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:
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:
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)
SCP Example

Part B: Offline Machine Installation

1

Install CLI (First Time Only)

Estimated time: 2 min
Skip if updating an existing installation. This is only for first-time installations.
Extract CLI tools and configuration:
Verify installation:
Future updates automatically update the CLI from airgap bundles—no manual transfer needed.
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:
Address any issues reported before proceeding with the installation. You will not be able to continue until all preflight checks pass.
3

Import AI Models

Estimated time: 5 to 30 min, depending on model sizes.Before importing Zylon, import the AI models that were exported on the online machine:
models import registers the model artifacts locally, and models download --offline installs them into the offline runtime.Verify models were installed successfully:
4

Import Airgap Bundle

Estimated time: 10 to 60 min, depending on bundle size and system performance.Import the Zylon bundle:
This process:
  • Extracts all container images
  • Installs dependencies offline
  • Prepares the system for installation
Import can take 30+ minutes depending on bundle size and system performance. Do not interrupt.
Verify that import completed successfully by checking installed versions:
5

Install Zylon

Estimated time: 15min to 1hour, depending on system performance.Install Zylon using the imported bundle:
The AI models have already been imported in a previous step, so no --models flag is needed here.
6

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)
  • 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
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, retrieve the one-time login password for the admin account:
Then log in with:
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:
If you see both files, proceed to install them as follows:Remove Automatic Certificate GenerationEdit /etc/zylon/zylon-conf.yaml and remove these lines:
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:
Import Certificate into Kubernetes
Apply ChangesReload the Zylon configuration:
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 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:
Download the new models:
Compare the available models with your AI preset requirements to determine if additional models are needed. See AI Presets documentation.
2

On Online Machine: Export New Models (If Applicable)

Estimated time: 5 to 30 min (only if new models were downloaded)Skip this step if you didn’t add new AI models.Export the newly downloaded models:
This creates a zylon-models-<timestamp>.tar file containing all currently downloaded models.
3

On Online Machine: Download Update

Estimated time: 10 to 60 minDownload the new Zylon version bundle:
Note that we no longer use the --models flag during download, as models are handled separately.
4

On Online Machine: Create Update Bundle

Estimated time: 10 to 60 minExport an incremental update bundle:
The --from flag creates a differential bundle containing only changes between versions, significantly reducing bundle size and transfer time.
Differential bundles are typically 5-20 GB vs. 60-80 GB for full bundles.
5

Transfer Bundle to Offline Machine

Transfer the bundle file(s) using your secure method:If you updated models:
If no new models:
Alternative methods:
  • USB drive
  • Internal file transfer system
  • Network share (if available)
6

On Offline Machine: Import New Models (If Applicable)

Estimated time: 5 to 30 min (only if new models were transferred)Skip this step if you didn’t transfer new AI models.Import the new models:
Verify models were installed successfully:
7

On Offline Machine: Import Update

Import the update bundle:
The import process:
  • Extracts container images for the new version
  • Updates system dependencies
  • Prepares upgrade artifacts
This may take 10-30 minutes. Don’t interrupt the process.
Verify that import completed successfully by checking installed versions:
8

On Offline Machine: Apply Update

Estimated time: 15 to 60 minApply the update to your running Zylon instance:
New AI models (if any) were already imported in a previous step, so no --models flag is needed here.

Migrating to Airgap

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
  • Target airgap machine with NO internet connection
  • Root and SSH access to all machines involved

Part A: Extract from Existing Zylon Machine

1

Extract Current Configuration

Estimated time: 5 minCopy the current Zylon configuration file:
2

Extract SSL Certificates

Estimated time: 5 minExtract the current SSL certificates from Kubernetes to avoid regeneration:
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:
Alternative methods:
  • USB drive
  • Secure internal file transfer
  • Network share

Part B: Prepare bundle on Online Machine

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:
Verify the installation:
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:
3

Reconfigure for Airgap

Estimated time: 10 minRun the configuration wizard to update settings for airgap deployment:
The wizard will guide you through updating the following settings:Potential Required Changes:
  1. Installation Type: Change from your current type (online/semi-airgap) to Airgap
  2. SSL Certificates: The wizard will prompt for certificates in text format:
  • Paste the contents of /tmp/tls.crt when prompted for the certificate
  • Paste the contents of /tmp/tls.key when prompted for the private key
When pasting certificates into the wizard:
  • Include the full content including -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- headers
  • Maintain proper line breaks and formatting
  • Do not add extra spaces or characters
  1. License Information (if changing channel):
    • License Email: Provided by Zylon team
    • License ID: Provided by Zylon team
    • License Data: Full license token provided by Zylon team
    Ensure the license data is copied exactly as provided, preserving formatting and line breaks.
  2. Channel (if applicable):
    • Change from stable to X (or as instructed by Zylon)
  3. Review All Other Settings: The wizard will display current values—confirm or update as needed
Verify Updated Configuration:
Confirm that everything is set correctly for AirGap operation.
4

Download Migration Bundle

Estimated time: 15 min to 1 hourDownload the Zylon version bundle (without AI models, as they already exist):
We’re not including --models flag because:
  • Existing AI models from your current installation will be preserved
  • If you need to add new models, include them with --models=model-a,model-b. More info in fresh installation guide below.
5

Export Migration Bundle

Estimated time: 15 to 60 minExport the migration bundle:
This creates zylon-<version>-<os>-<arch>.tar in your current directory.
6

Prepare Migration Package

Estimated time: 5 minCreate a complete migration package with CLI tools and configuration:
7

Transfer Files to Airgap Machine

Transfer the migration package to your airgap machine:Files to transfer:
  • zylon-<version>-<os>-<arch>.tar (main bundle)
  • zylon-migration.tar.gz (CLI and updated config)
SCP Example:

Part C: Migrate to Airgap on Offline Machine

1

Extract Migration Package

Estimated time: 2 minExtract the CLI tools and configuration:
Verify extraction:
Should show:
2

Verify System Requirements

Ensure the airgap machine meets all requirements:
Address any issues before proceeding.
3

Import Migration Bundle

Estimated time: 10 to 60 minImport the Zylon bundle:
This process:
  • Extracts all container images
  • Installs dependencies offline
  • Prepares the system for installation
Import can take 30+ minutes. Do not interrupt the process.
Verify import completion:
4

Install Zylon in Airgap Mode

Estimated time: 15 min to 1 hourInstall Zylon using the imported bundle:

Next Steps

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