Full-Airgap Installation

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.

Configuring Proxy Settings

Set the following environment variables before running any Zylon CLI commands:

export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"

Using Self-Signed CertificatesIf your proxy uses a self-signed certificate, you must also configure the CA certificate:

export SSL_CERT_FILE="/path/to/your/ca-cert.pem"
export REQUESTS_CA_BUNDLE="/path/to/your/ca-cert.pem"

Verify Proxy ConfigurationTest connectivity through the proxy before proceeding:

# Test HTTP connectivity
curl -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:

sudo -E zylon-cli download <version> --airgap

Installing Zylon

Online Machine

Download Zylon bundles and AI models with internet access

Transfer

Move bundle files to offline machine via secure transfer method

Offline Machine

Import and install Zylon without any internet connectivity

Part A: Online Machine Setup

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

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

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.Airgap SettingsEnsure these settings are included to indicate airgap installation and operation:

airgap:
  offline_install: true
  offline_operation: true

Local LicenseSince the offline machine cannot reach api.replicated.com, 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... 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.yaml
sudo vim /etc/zylon/zylon-conf.yaml

For detailed information about all available configuration options, see the Configuration Guide.

Download Zylon Bundle

Estimated time: 15min to 2h, depending on network speed.

First installation or additional models require AI models! Use the --models flag to specify which models to include.Check available models:

sudo zylon-cli forge list

Compare with your AI preset definition to determine required models. More preset details here.For example, if you preset is baseline-24g, include:

--models=qwen/qwen3-14b-awq,mixedbread-ai/mxbai-embed-large-v1

If you are using extra capabilities like multilingual, include:

--models=qwen/qwen3-14b-awq,intfloat/multilingual-e5-large

Download the specific Zylon version you want to install:

sudo zylon-cli list-versions
# Choose your desired version from the list
sudo zylon-cli download <version> --airgap [--models=model-a,model-b,model-c]

Replace <version> with your target version (e.g., 1.50.0). The --models flag is used to specify which AI models to include in the download. You can list multiple models separated by commas.

Export Bundle

Estimated time: 15 to 120 min, depending on selected models and version.Export the downloaded version into an airgap bundle. If you included models during download, ensure to include them here as well:

# Same version and models as download step
sudo zylon-cli export <version> [--models=model-a,model-b,model-c]

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 exceed 80GB.

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

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

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-initial.tar.gz (CLI and config)
zylon-ssl-certs.tar.gz (SSL certs, if applicable)

Subsequent updates:

zylon-<version>-<os>-<arch>.tar (main bundle only)

SCP Example

scp zylon-<version>-<os>-<arch>.tar user@offline-machine:/tmp/
scp zylon-initial.tar.gz user@offline-machine:/tmp/
scp zylon-ssl-certs.tar.gz user@offline-machine:/tmp/

Part B: Offline Machine Installation

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:

cd /tmp
sudo tar -xzf zylon-initial.tar.gz -C /
sudo chmod +x /usr/local/bin/zylon-cli /usr/local/bin/zylon-forge-cli

Verify installation:

sudo zylon-cli version
cat /etc/zylon/zylon-conf.yaml

Future updates automatically update the CLI from airgap bundles—no manual transfer needed.

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 --fresh-system -v

Address any issues reported before proceeding with the installation. You will not be able to continue until all preflight checks pass.

Import Airgap Bundle

Estimated time: 10 to 60 min, depending on bundle size and system performance.Import the Zylon bundle:

cd /tmp
sudo zylon-cli import zylon-<version>-<os>-<arch>.tar

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:

sudo zylon-cli list-versions --offline

Install Zylon

Estimated time: 15min to 1hour, depending on system performance.Install Zylon using the imported bundle, including airgap flag and models:

sudo zylon-cli install <version> --airgap [--models=model-a,model-b,model-c]

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 SSL Certificates (If applicable)

Estimated time: 10 minIf you prepared SSL certificates on the online machine, extract them now:

cd /tmp
sudo 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:

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

On Online Machine: Download Update

Download the new Zylon version bundle:

sudo zylon-cli download <new-version> --airgap

Adding New AI ModelsIf you need to add models not previously installed, include them:

sudo zylon-cli download <new-version> --airgap --models=new-model-a,new-model-b

Check your current models and available ones:

sudo zylon-cli forge list

Compare with your AI preset requirements to determine if additional models are needed.

On Online Machine: Create Update Bundle

Export an incremental update bundle:

sudo zylon-cli export <new-version> --from <current-version>

The --from flag creates a differential bundle containing only changes between versions, significantly reducing bundle size and transfer time.Include models (if applicable):If you change the preset, the GPU requirements, or need new models, include them:

sudo zylon-cli export <new-version> --from <current-version> --models=new-model-a,new-model-b

This generates zylon-<new-version>-to-<old-version>-<os>-<arch>.tar and displays the import/install commands to run on the offline machine as well.

Differential bundles are typically 5-20 GB vs. 80+ GB for full bundles.

Transfer Bundle to Offline Machine

Transfer the bundle file using your secure method:SCP Example:

scp zylon-<new-version>-to-<old-version>-<os>-<arch>.tar user@offline-machine:/tmp/

Alternative methods:

USB drive
Internal file transfer system
Network share (if available)

On Offline Machine: Import Update

Import the update bundle:

cd /tmp
sudo zylon-cli import zylon-<new-version>-to-<old-version>-<os>-<arch>.tar

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:

sudo zylon-cli list-versions --offline

On Offline Machine: Apply Update

Apply the update to your running Zylon instance:

sudo zylon-cli install <new-version> --airgap

If you included new models:

sudo zylon-cli install <new-version> --airgap --models=new-model-a,new-model-b

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

Extract Current Configuration

Estimated time: 5 minCopy the current Zylon configuration file:

# On existing Zylon machine
sudo cp /etc/zylon/zylon-conf.yaml /tmp/zylon-conf-backup.yaml

Extract SSL Certificates

Estimated time: 5 minExtract the current SSL certificates from Kubernetes to avoid regeneration:

# Extract certificate from Kubernetes secret
sudo k0s kubectl get secret zylon-tls -n zylon -o jsonpath='{.data.tls\.crt}' | base64 -d > /tmp/tls.crt
sudo k0s kubectl get secret zylon-tls -n zylon -o jsonpath='{.data.tls\.key}' | base64 -d > /tmp/tls.key

# Verify files were created
ls -lh /tmp/tls.crt /tmp/tls.key

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

Transfer Files to Online Machine

Transfer the configuration and certificates to your online machine:SCP Example:

# From existing Zylon machine to online machine
scp /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/

Alternative methods:

USB drive
Secure internal file transfer
Network share

Part B: Prepare bundle on Online Machine

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.

Transfer Configuration File

Estimated time: 2 minPlace the backed-up configuration in the correct location:

sudo mkdir -p /etc/zylon
sudo cp /tmp/zylon-conf-backup.yaml /etc/zylon/zylon-conf.yaml

Reconfigure for Airgap

Estimated time: 10 minRun the configuration wizard to update settings for airgap deployment:

sudo zylon-cli config init --force

The wizard will guide you through updating the following settings:Potential Required Changes:

Installation Type: Change from your current type (online/semi-airgap) to Airgap
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

How to view Certificate Contents:

# Display certificate (copy this output)
cat /tmp/tls.crt

# Display private key (copy this output)
cat /tmp/tls.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

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.
Channel (if applicable):
- Change from stable to X (or as instructed by Zylon)
Review All Other Settings: The wizard will display current values—confirm or update as needed

Verify Updated Configuration:

sudo cat /etc/zylon/zylon-conf.yaml

Confirm that everything is set correctly for AirGap operation.

Download Migration Bundle

Estimated time: 15 min to 1 hourDownload the Zylon version bundle (without AI models, as they already exist):

sudo zylon-cli list-versions
# Choose your target version
sudo zylon-cli download <version> --airgap

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.

Export Migration Bundle

Estimated time: 15 to 60 minExport the migration bundle:

sudo zylon-cli export <version>

This creates zylon-<version>-<os>-<arch>.tar in your current directory.

Prepare Migration Package

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

sudo tar -czf zylon-migration.tar.gz \
  /usr/local/bin/zylon-cli \
  /usr/local/bin/zylon-forge-cli \
  /etc/zylon/zylon-conf.yaml

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:

scp zylon-<version>-<os>-<arch>.tar user@airgap-machine:/tmp/
scp zylon-migration.tar.gz user@airgap-machine:/tmp/

Part C: Migrate to Airgap on Offline Machine

Extract Migration Package

Estimated time: 2 minExtract the CLI tools and configuration:

cd /tmp
sudo tar -xzf zylon-migration.tar.gz -C /
sudo chmod +x /usr/local/bin/zylon-cli /usr/local/bin/zylon-forge-cli

Verify extraction:

sudo zylon-cli version
cat /etc/zylon/zylon-conf.yaml

Should show:

airgap:
  offline_install: true
  offline_operation: true

Verify System Requirements

Ensure the airgap machine meets all requirements:

sudo zylon-cli preflight -v

Address any issues before proceeding.

Import Migration Bundle

Estimated time: 10 to 60 minImport the Zylon bundle:

cd /tmp
sudo zylon-cli import zylon-<version>-<os>-<arch>.tar

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:

sudo zylon-cli list-versions --offline

Install Zylon in Airgap Mode

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

sudo zylon-cli install <version> --airgap

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

Full-Airgap Installation

Required Network Access

Installing Zylon

Part A: Online Machine Setup

Part B: Offline Machine Installation

Updating Zylon

Migrating to Airgap

Part A: Extract from Existing Zylon Machine

Part B: Prepare bundle on Online Machine

Part C: Migrate to Airgap on Offline Machine

Next Steps

Getting Started

Installation

Configuration

Maintenance & Operations

Troubleshooting

​Required Network Access

​Installing Zylon

​Part A: Online Machine Setup

​Part B: Offline Machine Installation

​Updating Zylon

​Migrating to Airgap

​Part A: Extract from Existing Zylon Machine

​Part B: Prepare bundle on Online Machine

​Part C: Migrate to Airgap on Offline Machine

​Next Steps

Required Network Access

Installing Zylon

Part A: Online Machine Setup

Part B: Offline Machine Installation

Updating Zylon

Migrating to Airgap

Part A: Extract from Existing Zylon Machine

Part B: Prepare bundle on Online Machine

Part C: Migrate to Airgap on Offline Machine

Next Steps