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

# Upgrading to 1.58

> Steps to upgrade your Zylon installation to version 1.58.

<Warning>
  **Upcoming release — Zylon 1.58**

  These docs are published ahead of release so you can prepare your API integrations. The release image is not yet available. For installations running 1.57, use the [1.57 documentation](/en/v1.57/overview).
</Warning>

<Warning>
  **Zylon CLI 2.9.0 or later is required.** The commands used in this guide are not available in earlier CLI versions.
</Warning>

<Warning>
  If you maintain an API integration, review the [1.57 → 1.58 API migration guide](/en/v1.58/developer-manual/build-with-zylon/workspace-api/api-migration-1-57-to-1-58) before upgrading. Creator IDs now identify accounts; member operations still use workspace-member IDs. For clients that depend on these IDs, migrate the affected calls to the current API and [update saved ID mappings](/en/v1.58/developer-manual/build-with-zylon/workspace-api/api-migration-1-57-to-1-58#migrate-saved-user-ids). Legacy URLs do not preserve the complete 1.57 identity contract.
</Warning>

## What changed

1.58 requires two manual steps that the CLI does not run on its own. Run both once 1.58 is installed and all pods are ready:

* **Skill and Document backfill.** Existing Skills and Documents must be backfilled with `zylon-cli backfill-projections`.
* **Higher pod limit on the node.** The Kubernetes node must allow up to 200 pods. New installations get this limit automatically; existing installations apply it with `zylon-cli configure --max-pods 200`. This restarts k0s, so all Zylon services will be briefly unavailable.

If you use the `baseline-96g` preset, there is one more step before installing:

* **New `baseline-96g` model.** `baseline-96g` now runs `nvidia/Qwen3.8-27B-NVFP4` instead of `cyankiwi/qwen3.5-27b-awq-4bit`. Download it before installing 1.58. To keep the previous model, set `ai.preset: "deprecated.96g.20261008"`.

## How to upgrade

<Info>
  If you need help, [open a support ticket](https://zylonsupport.zendesk.com/hc/en-us/requests/new?tf_subject=1.58+Upgrade+Help) and our engineering team will assist you.
</Info>

### Step 1: Install 1.58

Follow the steps for your installation type.

<Tabs>
  <Tab title="Online">
    <Steps>
      <Step title="Update the CLI (required)">
        ```bash theme={null}
        sudo zylon-cli self-update
        ```

        If the command fails or the version does not change, run the fallback installer:

        ```bash theme={null}
        curl -sL get.zylon.ai | sudo -E bash
        ```

        ```bash theme={null}
        sudo zylon-cli version  # It should show 2.9.0 or later
        ```
      </Step>

      <Step title="Download the new 96g model (only for `baseline-96g`)">
        Skip this step if you do not use the `baseline-96g` preset.

        ```bash theme={null}
        sudo zylon-cli models download nvidia/Qwen3.8-27B-NVFP4
        ```
      </Step>

      <Step title="Install 1.58">
        ```bash theme={null}
        sudo zylon-cli list-versions
        sudo zylon-cli install 1.58.X
        ```
      </Step>
    </Steps>

    For full environment details and troubleshooting, see the [Online update guide](/en/v1.58/operator-manual/installation/online#updating-zylon).
  </Tab>

  <Tab title="Semi-Airgap">
    <Steps>
      <Step title="Update the CLI (required)">
        ```bash theme={null}
        sudo zylon-cli self-update
        ```

        If the command fails or the version does not change, run the fallback installer:

        ```bash theme={null}
        curl -sL get.zylon.ai | sudo -E bash
        ```

        ```bash theme={null}
        sudo zylon-cli version  # It should show 2.9.0 or later
        ```
      </Step>

      <Step title="Re-enable internet access">
        Temporarily allow online operations in your config, then apply it:

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

        ```bash theme={null}
        sudo zylon-cli sync
        ```
      </Step>

      <Step title="Verify connectivity">
        ```bash theme={null}
        sudo zylon-cli preflight --network -v
        ```
      </Step>

      <Step title="Download the new 96g model (only for `baseline-96g`)">
        Skip this step if you do not use the `baseline-96g` preset.

        ```bash theme={null}
        sudo zylon-cli models download nvidia/Qwen3.8-27B-NVFP4
        ```
      </Step>

      <Step title="Install 1.58">
        ```bash theme={null}
        sudo zylon-cli list-versions
        sudo zylon-cli install 1.58.X
        ```
      </Step>

      <Step title="Re-enable offline mode">
        ```yaml theme={null}
        airgap:
          offlineOperation: true
        ```

        ```bash theme={null}
        sudo zylon-cli sync
        ```
      </Step>
    </Steps>

    For networking and proxy guidance, see the [Semi-airgap update guide](/en/v1.58/operator-manual/installation/semi-airgap#updating-zylon).
  </Tab>

  <Tab title="Full Airgap">
    These steps run across two machines: an internet-connected machine for downloading, and the offline target machine.

    <Steps>
      <Step title="Online machine: update the CLI (required)">
        ```bash theme={null}
        sudo zylon-cli self-update
        ```

        If the command fails or the version does not change, run the fallback installer:

        ```bash theme={null}
        curl -sL get.zylon.ai | sudo -E bash
        ```

        ```bash theme={null}
        sudo zylon-cli version  # It should show 2.9.0 or later
        ```
      </Step>

      <Step title="Online machine: prepare the CLI transfer package">
        ```bash theme={null}
        sudo tar -czf zylon-update.tar.gz \
          /usr/local/bin/zylon-cli \
          /usr/local/bin/zylon-forge-cli
        ```
      </Step>

      <Step title="Online machine: download and export the new 96g model (only for `baseline-96g`)">
        Skip this step if you do not use the `baseline-96g` preset.

        ```bash theme={null}
        sudo zylon-cli models download --no-install nvidia/Qwen3.8-27B-NVFP4
        sudo zylon-cli models export
        ```
      </Step>

      <Step title="Online machine: export the 1.58 platform bundle">
        ```bash theme={null}
        sudo zylon-cli list-versions

        # Use --from if your current version is known (smaller bundle)
        sudo zylon-cli export 1.58.X --from CURRENT_VERSION

        # Otherwise export a full bundle
        sudo zylon-cli export 1.58.X
        ```
      </Step>

      <Step title="Transfer artifacts to the offline machine">
        Move the required files across your transfer medium:

        * `zylon-*.tar`
        * `zylon-update.tar.gz`
        * `zylon-models-<timestamp>.tar` (only for `baseline-96g`). Place it in its own folder on the offline machine, such as `/tmp/models`, so it is not picked up by `zylon-cli import zylon-*.tar`.
      </Step>

      <Step title="Offline machine: extract CLI transfer package">
        ```bash theme={null}
        cd /tmp
        sudo tar -xzf zylon-update.tar.gz -C /
        sudo chmod +x /usr/local/bin/zylon-cli /usr/local/bin/zylon-forge-cli
        sudo zylon-cli version  # It should show 2.9.0 or later
        ```
      </Step>

      <Step title="Offline machine: import the new 96g model (only for `baseline-96g`)">
        Skip this step if you do not use the `baseline-96g` preset.

        ```bash theme={null}
        cd /tmp/models
        sudo zylon-cli models import zylon-models-<timestamp>.tar
        sudo zylon-cli models download --offline
        sudo zylon-cli models list --installed
        ```
      </Step>

      <Step title="Offline machine: import and install">
        ```bash theme={null}
        # Import the Zylon bundle, check the new version is available, then install it
        sudo zylon-cli import zylon-*.tar
        sudo zylon-cli list-versions --offline
        sudo zylon-cli install 1.58.X --airgap
        ```
      </Step>
    </Steps>

    For differential bundle details and transfer guidance, see the [Full-airgap update guide](/en/v1.58/operator-manual/installation/airgap#updating-zylon).
  </Tab>
</Tabs>

### Step 2: Wait until all pods are ready

Wait until every pod in the `zylon` namespace shows all its containers ready (for example `1/1`) and `Running` (or `Completed` for jobs):

```bash theme={null}
watch sudo kubectl get pods -n zylon
```

### Step 3: Apply the 1.58 changes

Run the same commands for every installation type. No internet access is needed.

<Warning>
  The backfill rewrites existing Skills and Documents and cannot be undone. Always run it with `--dry-run` first and check the output before running it for real.
</Warning>

```bash theme={null}
# Check that commands can run inside the backend. It must succeed with no output.
# Right after a restart this can fail for a few minutes even if the pod shows 1/1; wait and retry.
sudo kubectl -n zylon exec deploy/zylon-zylon-backend -- true

# Preview the backfill of existing Skills and Documents. Nothing is changed.
# Check the last line: it must show failures=0. "planned" is how many will be written.
sudo zylon-cli backfill-projections --dry-run

# Only if the dry run went well: backfill existing Skills and Documents so they show up in 1.58.
# This change is irreversible.
sudo zylon-cli backfill-projections

# Show the current pod limit of the node. If it prints 110 (the Kubernetes default), it was never raised.
sudo kubectl get nodes -o jsonpath='{.items[*].status.capacity.pods}{"\n"}'

# Raise the Kubernetes pod limit to 200 (new installations already have it).
# This restarts k0s, so all Zylon services will be unavailable for a few minutes.
# If the limit is already 200, nothing changes and k0s is not restarted.
sudo zylon-cli configure --max-pods 200

# Once k0s is back, check the new limit. It must print 200.
sudo kubectl get nodes -o jsonpath='{.items[*].status.capacity.pods}{"\n"}'
```

The last line of each backfill run shows the result. Numbers depend on your data; `failures` must always be `0`:

```text theme={null}
# --dry-run: "planned" is what will be written, nothing is changed yet
Projection backfill complete: processed=178 content-migrated=0 projections-written=0 planned=43 skipped=135 failures=0

# Real run: the planned items are now written ("projections-written")
Projection backfill complete: processed=178 content-migrated=43 projections-written=43 planned=0 skipped=135 failures=0
```

<Info>
  Run the backfill before raising the pod limit: the backfill needs the platform running, and the k0s restart would interrupt it.
</Info>

## Troubleshooting

<AccordionGroup>
  <Accordion title="backfill-projections fails">
    If the error says `container not found ("zylon-backend")`, the node was restarted recently and is not ready to run commands yet. Wait a few minutes until `sudo kubectl -n zylon exec deploy/zylon-zylon-backend -- true` succeeds, then retry. Nothing was changed.

    Otherwise, make sure every pod in the `zylon` namespace is ready, run it again with `--dry-run` and check the output. If the dry run also fails, [open a support ticket](https://zylonsupport.zendesk.com/hc/en-us/requests/new?tf_subject=1.58+Upgrade+Help) before running the real backfill.
  </Accordion>

  <Accordion title="configure --max-pods cannot update the k0s configuration">
    The command only edits `/etc/k0s/k0s.yaml` when it matches the layout generated by the Zylon CLI. Otherwise it stops and prints the manual steps:

    1. Add `maxPods: 200` under `spec.workerProfiles` → `default` → `values` in `/etc/k0s/k0s.yaml`.
    2. Restart k0s:

    ```bash theme={null}
    sudo k0s stop && sudo k0s start
    ```

    3. Check that the new limit is active:

    ```bash theme={null}
    sudo grep maxPods /run/k0s/kubelet/config.yaml
    ```
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.