Update KoolBox

Any of these:

• Look at the bottom of the sidebar in the console, where it reads Powered by Koolify · v1.3.2 — whatever release is running. This appears from version 1.2.8; on 1.2.7 and earlier there is no version there at all.
• On the server: koolboxctl version — the one subcommand that needs no sudo
• On the server: curl http://127.0.0.1:3000/api/health

koolbox 1.3.2
bundled node v22.23.3
database schema 1.3.2

# Debian / Ubuntu
sudo apt update
apt-cache policy koolbox        # your version against the newest available
apt-cache madison koolbox       # every version still in the repository

# RHEL family
sudo dnf check-update koolbox
dnf --showduplicates list koolbox

The repository keeps the five newest versions of each package, which is also how far back you can roll back. The version listing is the quickest way to see exactly which five you have to choose from. On Debian and Ubuntu:

$ apt-cache madison koolbox
   koolbox |    1.3.2-1 | https://packages.koolify.ai/apt stable/main amd64 Packages
   koolbox |    1.3.1-1 | https://packages.koolify.ai/apt stable/main amd64 Packages
   koolbox |    1.3.0-1 | https://packages.koolify.ai/apt stable/main amd64 Packages
   koolbox |    1.2.8-1 | https://packages.koolify.ai/apt stable/main amd64 Packages
   koolbox |    1.2.7-1 | https://packages.koolify.ai/apt stable/main amd64 Packages

And on the RHEL family, where the check also reports an exit code:

$ sudo dnf --showduplicates list koolbox koolbox-full
Installed Packages
koolbox.x86_64                            1.3.0-1                       @koolbox
koolbox-full.noarch                       1.3.0-1                       @koolbox
Available Packages
koolbox.x86_64                            1.2.7-1                       koolbox
koolbox.x86_64                            1.2.8-1                       koolbox
koolbox.x86_64                            1.3.0-1                       koolbox
koolbox.x86_64                            1.3.1-1                       koolbox
koolbox.x86_64                            1.3.2-1                       koolbox

$ sudo dnf check-update koolbox ; echo $?
koolbox.x86_64                          1.3.2-1                          koolbox
100

This works on every version, needs nothing but your package manager, and is what the installer itself tells you to use:

# Debian / Ubuntu
sudo apt update && sudo apt install --only-upgrade koolbox koolbox-full

# RHEL family
sudo dnf upgrade koolbox koolbox-full

Name both packages. In practice either name works — koolbox-full declares Depends: koolbox (= <its own exact version>), so both resolvers move the pair together, and that was measured in both directions on both distributions: apt install -s --only-upgrade koolbox plans koolbox koolbox-full, dnf upgrade --assumeno koolbox plans the same two packages, and committing either put both on the new release. Naming both costs nothing and removes the question, so keep the habit.

What happens. The application in /opt/koolbox is replaced, new configuration settings introduced by the release are appended to your existing configuration file (your own values are never changed), the service restarts, and the database schema is brought up to date automatically. Your knowledge bases, chat history, workflows, users, audit logs, license and settings are all preserved. An upgrade took 15 seconds on Ubuntu and 23 on RHEL. When a release introduces new settings, the merge is explicit about it:

Added new setting: UPDATE_MANIFEST_URL
✓ Merged 1 new setting(s) into /etc/koolbox/koolbox.env.
Starting koolbox.service to apply schema changes...
✓ Service is ready (version 1.3.0, schema 1.3.0).
✓ Database schema is at version 1.3.0.

When it introduces none it says so — Configuration is already up to date. — and that same merge is available on its own as koolboxctl config --merge-defaults. Each of these claims was tested with hand-edited configuration values in place so that an overwrite would have been obvious: /opt/koolbox was replaced, every edited value survived byte-for-byte across both an upgrade and a downgrade, new settings were appended under their own header, and the installation identifier, the admin user and every table's row count were unchanged afterwards.

Confirm afterwards:

sudo koolboxctl status

Administration → Updates, and administrators only: a non-administrator sees no Updates link, no Administration section at all, and every call behind the page answers 403 Forbidden. Reaching the URL directly as a non-admin renders an empty page rather than a refusal, which looks broken but is not — the data and the actions are properly denied.

The first card, This installation, reports the two versions separately — Console version and Database schema — along with the address the console is being reached on, when it last checked, and whether the automatic daily check is enabled. The second card is the available release: its version, a stable channel chip, a Newer than installed or Installed state, the release date and the oldest version that can upgrade straight to it, the full release notes, and every artifact with its size. A Check now button forces a fresh check.

The Install an update card describes the division of labor in one line — “A privileged installer on this host carries the update out. The console's only part in it is to ask.” — which is exactly how it works, and why the console can update a package it has no privilege to install. Before it starts, it tells you plainly what an update costs:

Installing replaces this application and restarts the service, so this page stops
answering for roughly 30 to 90 seconds and everyone signed in is briefly disconnected.
Chat turns, workflow runs and uploads in flight are interrupted. Progress is shown
above and survives the restart.

That estimate is conservative: every apply measured here, from the console and from the command line, finished in 17 to 25 seconds.

Applying shows a seven-step checklist — queued, pre-flight checks, database backup, verifying the package signature, installing packages, applying schema migrations, health check — with a live elapsed timer. The page then survives the console restarting underneath it, which is the part most worth seeing:

Applying — the console is restarting
This page keeps checking and picks up the result on its own. Everyone signed in is
briefly disconnected and may have to sign in again. Do not reboot the host.

It reflects work done elsewhere, too: a koolboxctl rollback run over SSH appeared live in the same progress card and in Update history, which records the action, whether it was online or offline, the versions it moved between, the outcome, and who asked — an administrator's email for console runs, a dash for anything done with koolboxctl.

These four captures were taken across several releases as they shipped during verification, so the version numbers differ from one to the next — they are separate moments, not one continuous session.

The console checks once a day on its own and raises a notification for administrators. Both halves of that are worth understanding, because neither works the way the words usually imply.

The daily check is not a cron job or a systemd timer. There is no KoolBox timer and no entry in /etc/cron.d. The console runs its own scheduler on a one-minute tick — Scheduler started (1-minute tick…) in the log — and that tick does nothing at all until 24 hours have passed since the last check. The state lives in a database row, not a file, which is why it survives restarts and upgrades. If the console is not running, no check happens.

sudo koolboxctl update                   # guided: check, show the notes, confirm, apply, verify
koolboxctl update --check                # just report; needs no sudo
sudo koolboxctl update --to 1.3.1 --yes  # a named version, no questions
sudo koolboxctl update --offline <dir>   # from staged files, no network
sudo koolboxctl rollback [--to X.Y.Z]    # go back

The guided form shows you what it is about to do and why, then asks once. It is the whole interaction:

KoolBox update
  Installed version : 1.3.0
  Available version : 1.3.2 (stable channel)
  Released          : 2026-10-17T07:55:32Z

Release notes
  KoolBox 1.3.2

  A smaller download and a smaller footprint on disk, with no change to how the
  product behaves. Nothing here needs your attention if you are already on 1.3.1.

  The package no longer carries development files that a server never reads, so
  it installs about 12 MB lighter.

What will happen
  1. A database backup is taken (always, even with --yes).
  2. koolbox 1.3.2 is installed from the signed repository.
  3. The service restarts and applies its schema upgrade steps.
  4. Readiness is confirmed against http://127.0.0.1:3000/api/health.

! The console restarts. Signed-in users are briefly disconnected.

Update 1.3.0 → 1.3.2 now? [y/N] y

KoolBox update 1.3.0 → 1.3.2 (apply-online, online)
Checking this host is ready to update
✓ Preflight passed (1.3.0 → 1.3.2, online).
Backing up the database before updating
✓ Backup written: /var/lib/koolbox/backups/koolbox-1.3.0-20261017-102604.sql.gz
Installing koolbox 1.3.2
✓ Packages installed.
Applying schema upgrades and restarting the console
Waiting for the console to report 1.3.2
✓ Console is serving 1.3.2 (schema 1.3.2).
✓ KoolBox updated to 1.3.2.
  Phase       : completed
  Message     : Updated to 1.3.2
  Backup      : /var/lib/koolbox/backups/koolbox-1.3.0-20261017-102604.sql.gz
  Log         : /var/log/koolbox/update-cbc44baa-a366-4d6f-8675-f15c0f4b64f0.log

22 seconds, and the backup is not conditional — it happens even with --yes, which skips the question and nothing else. The prompt accepts y and treats everything else as no, without re-asking:

Update 1.3.0 → 1.3.2 now? [y/N] maybe
Aborted.

--to X.Y.Z installs the version you name even when a newer one is advertised, which is what you want when you are standardizing a fleet on a release you have tested. Each run leaves a log under /var/log/koolbox/.

Installed version : 1.3.0
✗ Could not fetch the update manifest from https://packages.koolify.ai/updates/latest.json
  This host may be offline or air-gapped. For an offline update use:
    sudo koolboxctl update --offline /path/to/packages

From 1.3.0 this is one command with a verified trust chain, and it is the route to use. The older package-manager route still works and is covered at the end.

1. 1

   On a connected machine, collect four files into one directory: the two packages for your distribution, the signed release manifest, and its signature.

   # Debian / Ubuntu — no sudo needed
   apt-get download koolbox koolbox-full
   
   # RHEL family — needs root
   sudo dnf download --resolve koolbox-1.3.2 koolbox-full-1.3.2
   
   curl -fLO https://packages.koolify.ai/updates/latest.json
   curl -fLO https://packages.koolify.ai/updates/latest.json.sig

   Take the version from the manifest and fetch packages that match it. A manifest and a package from different releases will fail verification — which is the point of the verification, but it is an avoidable afternoon.

2. 2

   Transfer the directory to the isolated server.

3. 3

   Apply it:

   sudo koolboxctl update --offline /path/to/dir

It lists what it found, verifies the manifest signature against a public key shipped inside the product, checks every package against the manifest, and only then installs. Measured end to end with the host's route to Koolify genuinely blocked, 17 to 19 seconds:

KoolBox offline update
  Installed version : 1.3.0
  Package version   : 1.3.2
  Staged in         : /var/lib/koolbox/update/staged/0dab11fa-2850-48f0-8059-7d426086a037
  Backup            : yes — taken before anything is installed
    koolbox-full_1.3.2-1_all.deb
    koolbox_1.3.2-1_amd64.deb
    latest.json
    latest.json.sig

! The console restarts. Signed-in users are briefly disconnected.

KoolBox update 1.3.0 → 1.3.2 (apply-offline, offline)
Checking this host is ready to update
✓ Preflight passed (1.3.0 → 1.3.2, offline).
Backing up the database before updating
✓ Backup written: /var/lib/koolbox/backups/koolbox-1.3.0-20261017-131235.sql.gz
Verifying the staged packages
✓ Release manifest signature verified against update-signing-key.pub.pem.
✓ Verified 2 package(s) against the signed manifest.
Installing koolbox 1.3.2
✓ Packages installed.
Applying schema upgrades and restarting the console
Waiting for the console to report 1.3.2
✓ Console is serving 1.3.2 (schema 1.3.2).
✓ Update applied.

# packages only
✗ The staged update has no release manifest (latest.json) — upload the manifest and its signature.

# manifest, no signature
✗ The staged release manifest has no detached signature (latest.json.sig).

# manifest altered by one byte, genuine signature
✗ The update manifest signature is not valid — refusing to act on it.
  Checked against /opt/koolbox/share/update-signing-key.pub.pem.

# genuine manifest and signature, package truncated by one byte
✓ Release manifest signature verified against update-signing-key.pub.pem.
✗ koolbox_1.3.2-1_amd64.deb does not match the checksum in the signed release manifest — the update was not applied.

A tampered manifest is rejected before anything happens at all — the signature is checked in the command itself, before the backup — while a missing manifest is discovered after it. Which means a failed offline attempt can still leave a database dump behind, and dumps rotate: five are kept, so several failed attempts in a row can push out a backup you wanted. Worth knowing before you experiment on a production server.

Uploading an update through the console

The same thing can be done from Administration → Updates, by uploading those four files into the Import an offline update package card. Each file is listed as it arrives with its byte count and SHA-256, the manifest is read and summarized, and the batch is verified as a whole before Install staged package becomes available.

!

This screen needs HTTPS, or it will not work at all.

Over plain http://your-server:3000 — which is exactly what the installer banner tells administrators to use — the card refuses to accept anything and says “This browser cannot generate a staging identifier. Use a current browser, or upload the package with koolboxctl.” The browser is not the problem: the card uses a function browsers only expose in a secure context, so it works over HTTPS or from localhost and nowhere else.

So either put the console behind HTTPS before you rely on this screen, or use sudo koolboxctl update --offline, which has no such constraint. On an air-gapped server the command line is the dependable route.

i

Two “Missing” rows are expected. The verification list covers all four artifacts in the release, which includes the RPMs on a Debian host and the Debian packages on a RHEL host. Two rows reading Missing alongside two reading Match is a complete batch for your distribution, and it does not block the install.

An incomplete batch is accepted and held rather than rejected: the package is staged with its checksum shown and the version to install already filled in, while the install button stays disabled and the card tells you precisely what is missing — Incomplete — keep uploading. Upload the signed release manifest (latest.json) and its signature (latest.json.sig). or, once the manifest is there, Incomplete — keep uploading. Upload the manifest signature (latest.json.sig). A corrupted package instead reports Verification failed and names the file to delete and upload again.

# Debian / Ubuntu — silent, 16 to 18 seconds
sudo apt-get install -y ./koolbox_*.deb ./koolbox-full_*.deb

# RHEL family — --disablerepo is required when the repository is unreachable
sudo dnf install --disablerepo=koolbox ./koolbox-*.rpm ./koolbox-full-*.rpm

The product is an ordinary repository package, so your distribution's own unattended-update mechanism can keep it current.

sudo apt install -y unattended-upgrades
sudo tee /etc/apt/apt.conf.d/52koolbox-unattended >/dev/null <<'EOF'
Unattended-Upgrade::Allowed-Origins { "Koolify Inc:stable"; };
EOF
sudo unattended-upgrade --dry-run --debug

sudo dnf install -y dnf-automatic
sudo nano /etc/dnf/automatic.conf        # set apply_updates = yes
sudo systemctl enable --now dnf-automatic.timer

Take one before any significant change. It takes well under a second.

sudo koolboxctl backup

The file is written to /var/lib/koolbox/backups/ with the version and timestamp in its name. The five newest are kept and older ones are removed automatically — verified: taking a sixth backup pruned the oldest. Set KOOLBOX_BACKUP_KEEP in the environment to keep a different number, and bear in mind that a failed offline update writes a dump too, so it consumes one of the five.

To write one somewhere else — a mounted network share, for example — name the path. Both forms print where they wrote and how big it was:

sudo koolboxctl backup /mnt/nas/koolbox-nightly.sql.gz

$ sudo koolboxctl backup
Backing up koolbox → /var/lib/koolbox/backups/koolbox-1.3.2-20261017-152154.sql.gz
✓ Backup written: /var/lib/koolbox/backups/koolbox-1.3.2-20261017-152154.sql.gz (16K)

$ sudo koolboxctl backup /tmp/koolbox-custom-path.sql.gz
Backing up koolbox → /tmp/koolbox-custom-path.sql.gz
✓ Backup written: /tmp/koolbox-custom-path.sql.gz (16K)

A nightly backup is a reasonable addition to your crontab:

15 2 * * * /usr/bin/koolboxctl backup >/dev/null 2>&1

sudo koolboxctl restore /var/lib/koolbox/backups/koolbox-1.3.2-20261017-152154.sql.gz

! This replaces the ENTIRE contents of database 'koolbox' on localhost.
! All current knowledge bases, chat history, workflows, users, and audit logs will be overwritten.
Type the database name to confirm: koolbox
Stopping koolbox.service...
Restoring from /var/lib/koolbox/backups/koolbox-1.3.2-20261017-152154.sql.gz...
 set_config
------------

(1 row)

ERROR:  must be owner of extension unaccent
ERROR:  must be owner of extension pg_trgm
ERROR:  must be owner of extension pg_trgm
ERROR:  must be owner of extension unaccent
✓ Restore completed.
Waiting for the service to become ready (up to 120s)...
✓ Service is ready (version 1.3.2, schema 1.3.2).

Type the database name to confirm: yes
✗ Confirmation did not match — aborted.

The five newest releases stay available, so you can return to any of them. From 1.3.0 there is a command for it, and it is the one to use — it takes a backup first, tells you what it will and will not undo, and verifies the console afterwards:

sudo koolboxctl rollback               # the version you were on before the last update
sudo koolboxctl rollback --to 1.3.0    # a specific release
sudo koolboxctl rollback --to 1.3.0 --yes

With no --to it works out where you came from — No --to given; using 1.3.0, from the newest pre-upgrade backup. — and then puts the question in front of you properly:

KoolBox rollback
  Installed version : 1.3.2
  Rolling back to   : 1.3.0
  Backup            : yes — taken before anything is installed

! A rollback installs the older package. It does NOT restore the database.
! An older release may not understand a schema a newer one upgraded; if the
! console fails to start, restore the pre-upgrade dump as well.

  Newest backup: /var/lib/koolbox/backups/koolbox-1.3.0-20261017-102604.sql.gz
  Restore it with: sudo koolboxctl restore /var/lib/koolbox/backups/koolbox-1.3.0-20261017-102604.sql.gz
! The console restarts. Signed-in users are briefly disconnected.

Roll back 1.3.2 → 1.3.0 now? [y/N] y

KoolBox update 1.3.2 → 1.3.0 (rollback, online)
Checking this host is ready to update
✓ Preflight passed (1.3.2 → 1.3.0, online).
Backing up the database before updating
✓ Backup written: /var/lib/koolbox/backups/koolbox-1.3.2-20261017-102800.sql.gz
Installing koolbox 1.3.0
✓ Packages installed.
Applying schema upgrades and restarting the console
Waiting for the console to report 1.3.0
✓ Console is serving 1.3.0 (schema 1.3.2).
✓ KoolBox rolled back to 1.3.0.
  Phase       : rolled-back
  Message     : Rolled back to 1.3.0

Eight rollbacks were run during verification, all successful, 20 to 21 seconds each. A no-op is handled gracefully (✓ KoolBox is already at 1.3.0 — nothing to do.), and a rollback immediately after an update tends to work even with no route to the repository, because the older package is still in your package manager's cache — useful, but not something to rely on.

# Debian / Ubuntu — see what is available, then install it
apt-cache madison koolbox
sudo apt install koolbox=1.3.0-1 koolbox-full=1.3.0-1

# RHEL family
dnf --showduplicates list koolbox
sudo dnf downgrade koolbox koolbox-full

Afterwards the health report legitimately shows two different versions — the running code is older than the schema it is reading:

$ koolboxctl version
koolbox 1.3.0
bundled node v22.23.3
database schema 1.3.2

sudo koolboxctl restore /var/lib/koolbox/backups/<the-backup-from-before>.sql.gz