Upgrading to 1.58

Upcoming release — Zylon 1.58These 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.

Zylon CLI 2.9.0 or later is required. The commands used in this guide are not available in earlier CLI versions.

If you maintain an API integration, review the 1.57 → 1.58 API migration guide 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. Legacy URLs do not preserve the complete 1.57 identity contract.

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

If you need help, open a support ticket and our engineering team will assist you.

Step 1: Install 1.58

Follow the steps for your installation type.

Online
Semi-Airgap
Full Airgap

Update the CLI (required)

sudo zylon-cli self-update

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

curl -sL get.zylon.ai | sudo -E bash

sudo zylon-cli version  # It should show 2.9.0 or later

Download the new 96g model (only for baseline-96g)

Skip this step if you do not use the baseline-96g preset.

sudo zylon-cli models download nvidia/Qwen3.8-27B-NVFP4

Install 1.58

sudo zylon-cli list-versions
sudo zylon-cli install 1.58.X

For full environment details and troubleshooting, see the Online update guide.

Update the CLI (required)

sudo zylon-cli self-update

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

curl -sL get.zylon.ai | sudo -E bash

sudo zylon-cli version  # It should show 2.9.0 or later

Re-enable internet access

Temporarily allow online operations in your config, then apply it:

airgap:
  offlineOperation: false

sudo zylon-cli sync

Verify connectivity

sudo zylon-cli preflight --network -v

Download the new 96g model (only for baseline-96g)

Skip this step if you do not use the baseline-96g preset.

sudo zylon-cli models download nvidia/Qwen3.8-27B-NVFP4

Install 1.58

sudo zylon-cli list-versions
sudo zylon-cli install 1.58.X

Re-enable offline mode

airgap:
  offlineOperation: true

sudo zylon-cli sync

For networking and proxy guidance, see the Semi-airgap update guide.

These steps run across two machines: an internet-connected machine for downloading, and the offline target machine.

Online machine: update the CLI (required)

sudo zylon-cli self-update

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

curl -sL get.zylon.ai | sudo -E bash

sudo zylon-cli version  # It should show 2.9.0 or later

Online machine: prepare the CLI transfer package

sudo tar -czf zylon-update.tar.gz \
  /usr/local/bin/zylon-cli \
  /usr/local/bin/zylon-forge-cli

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.

sudo zylon-cli models download --no-install nvidia/Qwen3.8-27B-NVFP4
sudo zylon-cli models export

Online machine: export the 1.58 platform bundle

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

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.

Offline machine: extract CLI transfer package

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

Offline machine: import the new 96g model (only for baseline-96g)

Skip this step if you do not use the baseline-96g preset.

cd /tmp/models
sudo zylon-cli models import zylon-models-<timestamp>.tar
sudo zylon-cli models download --offline
sudo zylon-cli models list --installed

Offline machine: import and install

# 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

For differential bundle details and transfer guidance, see the Full-airgap update guide.

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

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.

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.

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

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

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

Troubleshooting

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 before running the real backfill.

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:

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

sudo k0s stop && sudo k0s start

Check that the new limit is active:

sudo grep maxPods /run/k0s/kubelet/config.yaml

​What changed

​How to upgrade

​Step 1: Install 1.58

​Step 2: Wait until all pods are ready

​Step 3: Apply the 1.58 changes

​Troubleshooting

What changed

How to upgrade

Step 1: Install 1.58

Step 2: Wait until all pods are ready

Step 3: Apply the 1.58 changes

Troubleshooting