> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zylon.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Semi-Airgap Installation

> Install Zylon in environments with restricted internet access

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](/en/operator-manual/installation/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](/en/operator-manual/installation/semi-airgap#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

<Info>
  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](/en/operator-manual/installation/airgap).
</Info>

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

<Steps>
  <Step title="Install Zylon CLI">
    *Estimated time: 2 min*

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

      ```bash theme={null}
      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.
    </Warning>

    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:

    ```bash theme={null}
    # ssh <user>@<host-ip>
    sudo curl -sL get.zylon.ai | sh
    ```

    Verify the installation:

    ```bash theme={null}
    sudo zylon-cli version
    ```

    <Note>
      Root access is required for CLI operations as it manages system-level dependencies and configurations.
    </Note>
  </Step>

  <Step title="Verify Zylon minimum requirements">
    Ensure your machine meets the [hardware requirements](/en/operator-manual/installation/hardware-requirements) for Zylon.

    To validate automatically if your installation meets the minimum requirements, run:

    ```bash theme={null}
    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.

    <Info>
      Are you having issues with network connectivity? Consider moving to an [Airgap Installation](/en/operator-manual/installation/airgap).
    </Info>

    <Note>
      Zylon requires all checks to pass before providing installation support.
    </Note>
  </Step>

  <Step title="Configure Zylon">
    *Estimated time: 10min*

    Zylon is configured using a YAML file located at `/etc/zylon/zylon-conf.yaml`.

    **Generate Initial Configuration**

    Use the CLI to generate an initial configuration file:

    ```bash theme={null}
    sudo zylon-cli config init
    ```

    This opens an interactive prompt to guide you through configuration options.

    <Info>
      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:

      ```bash theme={null}
      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](#manual-configuration) section.
    </Info>

    <Tabs>
      <Tab title="Auto 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](#manual-configuration) section.

        <Info>
          If you need to re-run the configuration wizard, execute:

          ```bash theme={null}
          sudo zylon-cli config init
          ```
        </Info>

        You can
      </Tab>

      <Tab title="Manual Configuration">
        Edit `/etc/zylon/zylon-conf.yaml` to adjust settings as needed.

        **Define your OS distribution**

        Set `node.distro` to match your Ubuntu version:

        ```yaml theme={null}
        node:
          distro: "ubuntu22"  # for Ubuntu 22.04
          # distro: "ubuntu24"  # for Ubuntu 24.04
        ```

        **Define your CPU architecture**

        Set `node.arch` to match your hardware:

        ```yaml theme={null}
        node:
          arch: "amd64"  # for Intel/AMD processors
        ```

        **Set your hardware drivers (if applicable)**

        Set `node.drivers` to `generic` (this is the only supported option):

        ```yaml theme={null}
        node:
          drivers: "generic"
        ```

        **Configure cluster type**

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

        ```yaml theme={null}
        cluster:
          type: "k0s"
        ```

        **Select your release channel**

        Set `channel` to `stable` (recommended for production and normal use) or `unstable` (available under request for testing):

        ```yaml theme={null}
        channel: "stable"
        ```

        **Add your license information**

        Set `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:

        ```yaml theme={null}
        license:
          email: "champion@company.com"
          id: "2oq..."
        ```

        **Choose your AI preset**

        Set `ai.preset` based on your available GPU memory. See [AI Presets](/en/operator-manual/ai-presets/getting-started) for details.

        ```yaml theme={null}
        ai:
          preset: "baseline-48g"
        ```

        **Set your company identifier**

        Set `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`):

        ```yaml theme={null}
        companyIdentifier: "your-company"
        ```

        **Disable telemetry & crash reporting**

        To disable telemetry and crash reporting, add the following section:

        ```yaml theme={null}
        observability:
            crashReporting: false
            usageMetrics: false
        ```

        **Configure network ingress**

        Set `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`

        ```yaml theme={null}
        ingress:
          host: "zylon.your-company.com"
          enabled: true
          tlsEnabled: true
        ```

        **Configure SSL certificate generation**

        If your server is accessible from the internet, Let's Encrypt will automatically generate and renew SSL certificates. Keep the default `certManagerAnnotations`:

        ```yaml theme={null}
        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](#disable-lets-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:

        ```yaml theme={null}
        license:
          email: "champion@company.com"
          id: "2xo..."
          type: "Zylon"
          data: |-
            [eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...]
        ```

        <Warning>
          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...`.
        </Warning>

        **Proxy configuration (If Needed)**

        Refer to the [Proxy Configuration Guide](/en/operator-manual/configuration/network/proxy) to set up proxy settings in your configuration.

        **Disable Let's Encrypt**

        Edit `/etc/zylon/zylon-conf.yaml` and **remove** these lines:

        ```yaml theme={null}
        certManagerAnnotations:
          cert-manager.io/cluster-issuer: "letsencrypt-prod"
        ```
      </Tab>
    </Tabs>

    **View Current Configuration**

    ```bash theme={null}
    sudo cat /etc/zylon/zylon-conf.yaml
    ```

    You can edit the configuration file directly using your preferred text editor (e.g., `nano`, `vim`):

    ```bash theme={null}
    # 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](/en/operator-manual/configuration/index).
  </Step>

  <Step title="Download AI Models">
    *Estimated time: 10min to 1h, depending on network speed and models.*

    **Before installing Zylon**, you must download the AI models. The models are determined by your AI preset configuration and will be downloaded from Hugging Face domains.

    Ensure your firewall allows access to:

    * `huggingface.co`
    * `xet.huggingface.co`

    Check available models and compare with your AI preset:

    ```bash theme={null}
    sudo zylon-cli models list
    ```

    More preset details in the [AI Presets documentation](/en/operator-manual/ai-presets/presets).

    Download the models based on your configuration:

    ```bash theme={null}
    sudo zylon-cli models download
    ```

    This will download and install 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:

    ```bash theme={null}
    sudo zylon-cli models list
    sudo zylon-cli models download model-a model-b model-c
    ```

    For example, for `baseline-48g` preset:

    ```bash theme={null}
    sudo zylon-cli models download qwen/qwen3-14b-awq mixedbread-ai/mxbai-embed-large-v1
    ```
  </Step>

  <Step title="Install Zylon">
    *Estimated time: 15min to 1hour, depending on system performance and network speed.*

    Run the installation with your desired version:

    ```bash theme={null}
    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](https://k0sproject.io/))
    * NVIDIA drivers and CUDA (if applicable)
    * Container runtime and tools (kubectl, helm)
    * Zylon container images
    * SSL certificate generation (if using Let's Encrypt)

    <Note>
      Note that AI models are **not** included in this step—they were installed in the previous step.
    </Note>

    **Monitor Installation**

    Watch the installation progress:

    ```bash theme={null}
    # Watch Zylon pods
    watch sudo k0s kubectl get pods -n zylon

    # Watch GPU validation (if applicable)
    watch sudo k0s kubectl get pods -n nvidia
    ```

    Wait until all pods show `1/1` ready status.

    <Tip>
      **Reboot after installation** to ensure GPU drivers load properly.
    </Tip>

    <Danger>
      **Kernel upgrades can break NVIDIA drivers!**

      Test drivers with: `nvidia-smi`

      Troubleshooting: [NVIDIA Drivers Guide](/en/operator-manual/troubleshooting/nvidia-drivers)
    </Danger>

    <Warning>
      If services remain in `ContainerCrashLoopBackOff` for over 1 hour, contact support with logs.
    </Warning>

    Installation may take 15-60 minutes depending on network speed and firewall restrictions.
  </Step>

  <Step title="Create Organization">
    *Estimated time: 5 min*

    After Zylon is installed and running, create your organization and root administrator account.

    **Prepare Information**

    You'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**

    ```bash theme={null}
    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.

    <Danger>
      **Running the seed command will WIPE ALL DATA.** Only run this once during the initial Zylon setup.
    </Danger>

    **Login Credentials**

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

    <Note>
      After first login, you can create additional administrators and configure SSO authentication.
    </Note>
  </Step>

  <Step title="Configure Offline Operation">
    *Estimated time: 5 min*

    After 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:

    ```yaml theme={null}
    airgap:
      offlineOperation: true
    ```

    And sync the configuration:

    ```bash theme={null}
    sudo zylon-cli sync
    ```

    This will disable connectivity in AI, K8s and other subsystems.
  </Step>

  <Step title="Configure SSL (Optional)">
    *Estimated time: 10 min*

    For VPN or private network deployments, you need to manually install SSL certificates.

    **Remove Automatic Certificate Generation**

    Edit `/etc/zylon/zylon-conf.yaml` and **remove** these lines:

    ```yaml theme={null}
    certManagerAnnotations:
      cert-manager.io/cluster-issuer: "letsencrypt-prod"
    ```

    **Prepare Certificate Files**

    Kubernetes 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:

    ```bash theme={null}
    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**

    ```bash theme={null}
    # 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 Changes**

    Reload the Zylon configuration:

    ```bash theme={null}
    sudo zylon-cli sync
    ```

    **Verify**

    Access 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

    <Tip>
      Certificate renewal must be done manually by repeating this process with updated certificate files.
    </Tip>
  </Step>
</Steps>

***

## 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:

```yaml theme={null}
airgap:
  offlineOperation: false
```

Validate if Zylon has connectivity again by running:

```bash theme={null}
sudo zylon-cli preflight --network -v
```

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

```bash theme={null}
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:

```bash theme={null}
sudo zylon-cli upgrade
```

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

```yaml theme={null}
airgap:
  offlineOperation: 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.

<Info>
  **Migration differs from fresh installation:**

  * Your existing configuration and data will be preserved
  * SSL certificates will be migrated
  * Organization and users already exist
</Info>

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

1. **Ensure connectivity**: Verify that the target machine has connectivity with below domains.
2. **Update configuration**: Run `sudo zylon-cli config init` to update the configuration for online operation. Be sure to configure as [Configure Zylon](#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.

4. **Disable offline mode**: Edit `/etc/zylon/zylon-conf.yaml` and set:
   ```yaml theme={null}
   airgap:
     offlineOperation: false
   ```
5. **Refresh configuration**: Execute `sudo zylon-cli sync` to apply the new configuration settings.
6. **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](/en/operator-manual/ai-presets) to optimize for your hardware
* [Configure Backups](/en/operator-manual/operations/backup) for data protection
* [Review User Manual](/en/user-manual/quick-start-guide) to get started