Install KoolBox

Not on the list? The installer stops and tells you, rather than installing something that cannot work. It names the family it detected, so you can see it guessed right.

No Red Hat subscription is needed on the RHEL family: on the verification run, every dependency — PostgreSQL, LibreOffice and Java 17 included — came from the image's own baseos and appstream repositories.

To check what you have, run:

cat /etc/os-release
uname -m

uname -m must print x86_64 (some tools call it amd64).

• Memory: 4 GB minimum, 8 GB recommended. This matters more than it sounds. Installing and upgrading unpacks several hundred megabytes, and on a 1 GB machine the operating system can terminate the package manager partway through, which leaves a half-installed package you have to repair by hand.
• Disk: 20 GB.
• PostgreSQL 13 or newer. Either on the same server (the installer can set this up for you) or reachable over the network — Amazon RDS, Azure Database for PostgreSQL, or a cluster you already run. RHEL 9 ships PostgreSQL 13 exactly — the minimum, with no margin, which is why releases before 1.3.0 had trouble there. Ubuntu 24.04 ships 16.

Check memory and disk with:

free -m          # look at the "total" column under Mem
df -h /          # look at the "Avail" column

There are two. Pick one now; you can change later, but it is easier to choose correctly.

Log in to your server and run one of these. Everything on one server, including the database:

curl -fsSL https://packages.koolify.ai/install.sh | sudo sh -s -- --full

Console only, because your database is elsewhere:

curl -fsSL https://packages.koolify.ai/install.sh | sudo sh

curl -fsSL https://packages.koolify.ai/install.sh -o install.sh
sudo sh install.sh --full

Piped on RHEL, the key-import prompt consumes the script and you see this instead:

Importing GPG key 0x403BE624:
 Fingerprint: 9F1B A391 E54B 66E9 6F25 E3E1 17BB 084F 403B E624
Is this ok [y/N]: Error: Failed to download metadata for repo 'koolbox': repomd.xml GPG signature verification error: Bad GPG signature

The install still proceeds correctly — dnf install -y imports the key itself a moment later — so that Bad GPG signature line is expected and harmless. What you lose is the script's closing Installation finished. Check the service with: sudo koolboxctl status, which never prints. Running the same script from a file prints it.

What this does. The script detects your distribution, installs Koolify's package-signing key so your system can verify what it downloads, registers the Koolify package repository, and then hands over to your normal package manager. It contains no application code. After it has run once, updates are ordinary apt or dnf operations.

Useful options, added after -s -- in the piped form, or straight after the script name in the two-step form. --full and --version work together:

The following packages have unmet dependencies:
 koolbox-full : Depends: koolbox (= 1.3.0-1) but 1.3.1-1 is to be installed
                Recommends: libreoffice-core but it is not going to be installed
                Recommends: libreoffice-writer but it is not going to be installed
E: Unable to correct problems, you have held broken packages.
ERROR: Version 1.3.0 is not available. List versions with: apt-cache madison koolbox-full

The working form on Debian and Ubuntu is two steps: register the repository, then name both packages at the version you want. The -1 package revision is part of the version string and is required — koolbox=1.3.0 is not a valid version:

sudo sh -c "$(curl -fsSL https://packages.koolify.ai/install.sh)" -- --full --repo-only
sudo apt-get install -y koolbox=1.3.0-1 koolbox-full=1.3.0-1

That completed in 1 m 12 s on a clean server. On the RHEL family the one-line form with --version does work, because dnf resolves the pinned dependency rather than giving up:

curl -fsSL https://packages.koolify.ai/install.sh -o install.sh
sudo sh install.sh --full --version 1.3.0

What you should see. Part-way through the run — about 110 lines before the end on Ubuntu, at line 1209 of a 1319-line install — the console package's own post-install step prints a boxed banner with everything you need:

Setting up koolbox (1.3.0-1) ...
Installing KoolBox 1.3.0
✓ Generated JWT signing secret.
✓ Generated database password for role 'koolbox'.
✓ Created PostgreSQL role 'koolbox'.
✓ Created database 'koolbox'.
✓ Ensured PostgreSQL extensions (unaccent, pg_trgm).
✓ Enabled scram-sha-256 password authentication for 'koolbox' on koolbox (loopback only).
✓ Verified database connectivity as 'koolbox'.
✓ Configuration complete.
Starting koolbox.service to apply schema changes...
Waiting for the service to become ready (up to 120s)...
✓ Service is ready (version 1.3.0, schema 1.3.0).
✓ Database schema is at version 1.3.0.

────────────────────────────────────────────────────────────────────────────
KoolBox Private AI Control Panel 1.3.0 is running.

  Console        http://203.0.113.10:3000
  Sign in        admin@local.koolbox / ChangeMe123!   ← change immediately

Next steps
  1. Sign in and set a new administrator password.
  2. Activate your license: Settings → License & Activation.
     A 3-day grace period starts now; online and offline (air-gapped)
     activation are both supported.
  3. Register your private AI nodes and deploy models.

Administration
  koolboxctl status              health, versions, database, backups
  koolboxctl backup              on-demand database backup
  systemctl restart koolbox      apply configuration changes
  journalctl -u koolbox -f       live logs

Optional: install LibreOffice to enable PDF/ODT document generation.
────────────────────────────────────────────────────────────────────────────

Installation finished. Check the service with:
  sudo koolboxctl status

Future upgrades use the system package manager:
  sudo apt update && sudo apt install --only-upgrade koolbox koolbox-full

Scroll back for the banner, or just run sudo koolboxctl status, which tells you the same things and is covered under Confirm the installation worked. Three details in that banner are worth knowing before you follow it:

• The Console URL may not be reachable. It is whatever hostname -I returns, which on a cloud server is the private address — see First sign-in.
• Settings → License & Activation does not exist. The License page is at Administration → License. That section holds exactly six items — Groups / Users, Import / Export, License, Security, Settings and Updates — and nothing called “License & Activation” anywhere. The banner's wording is a product bug, still present on 1.3.2, not a different build.
• Ignore the LibreOffice line on a --full install. It is not optional and it is not missing: koolbox-full recommends libreoffice-core and libreoffice-writer, so apt is installing them later in the same run — around 120 MB of LibreOffice and X11. What PDF output actually needs is one restart.

On the RHEL family the shape is the same but the wording differs slightly, and the run ends with Complete! followed by the same two closing blocks. A clean RHEL 9.6 server was up and healthy in 49 to 52 seconds, twice.

If you installed koolbox on its own, without --full, the run instead prints a boxed KoolBox is installed but not yet started banner. That is the expected message when PostgreSQL is not on this server, and Method C takes it from there. On a --full install you may see that same box go past mid-run, printed before the database has been set up — in that case it is stale and you should not follow it.

Use this if your policy forbids piping a script to a shell. The result really is identical to Method A — on Ubuntu the two produce a byte-for-byte identical /etc/apt/sources.list.d/koolbox.sources.

Ubuntu and Debian:

sudo apt update
sudo apt install -y curl gnupg ca-certificates

# Install Koolify's signing key
curl -fsSL https://packages.koolify.ai/koolbox.asc \
  | sudo gpg --dearmor -o /usr/share/keyrings/koolbox-archive-keyring.gpg
sudo chmod 0644 /usr/share/keyrings/koolbox-archive-keyring.gpg

# Register the repository
sudo tee /etc/apt/sources.list.d/koolbox.sources >/dev/null <<'EOF'
Types: deb
URIs: https://packages.koolify.ai/apt
Suites: stable
Components: main
Architectures: amd64
Signed-By: /usr/share/keyrings/koolbox-archive-keyring.gpg
EOF

sudo apt update
sudo apt install -y koolbox-full       # or: koolbox

Leave Architectures: amd64 as it is. Changing it to arm64 does not give you an ARM install — that index carries no console package — see ARM servers.

RHEL, Rocky Linux, AlmaLinux and Fedora:

sudo curl -fsSL -o /etc/yum.repos.d/koolbox.repo \
  https://packages.koolify.ai/koolbox.repo
sudo rpm --import https://packages.koolify.ai/koolbox.asc
sudo dnf install -y koolbox-full       # or: koolbox

These are only for a first install. If you have already run Method A, both steps are redundant and harmless: /etc/yum.repos.d/koolbox.repo already exists and re-downloading it only adds a comment header — the [koolbox] stanza is byte-identical — and rpm --import on an already-imported key prints nothing and exits 0.

If you installed koolbox and PostgreSQL is elsewhere, the service is deliberately left stopped until you tell it where the database is. Nothing is broken; it is waiting for you.

1. 1

   On your database server, create the database, a user, and the two extensions the product needs for keyword search:

   CREATE USER koolbox WITH PASSWORD 'choose-a-strong-password';
   CREATE DATABASE koolbox OWNER koolbox;
   \c koolbox
   CREATE EXTENSION IF NOT EXISTS unaccent;
   CREATE EXTENSION IF NOT EXISTS pg_trgm;

2. 2

   On the KoolBox server, open the configuration file:

   sudo nano /etc/koolbox/koolbox.env

   Set these five values, then save (Ctrl+O, Enter) and exit (Ctrl+X):

   DB_HOST=db.example.internal
   DB_PORT=5432
   DB_NAME=koolbox
   DB_USER=koolbox
   DB_PASSWORD=choose-a-strong-password

   If your password contains a # or a $, wrap the whole value in double quotes.

3. 3

   Verify the connection and start up:

   sudo koolboxctl setup      # checks the connection, enables the extensions
   sudo koolboxctl migrate    # creates the tables and starts the service

A host name containing a dot turns on TLS to the database automatically, which is what managed services such as RDS require.

This is the one install method that was not exercised on the verification servers, which both ran their database locally. The commands are the same ones koolbox-full runs for you; what we could not measure is a managed provider's own behavior.

The packages have no network dependencies beyond ordinary operating-system packages, so they install fine on an isolated server. The work is in the download, and the two distributions behave so differently here that they are worth reading separately.

Debian and Ubuntu. Download on any connected machine of the same distribution — no sudo needed, it writes into the current directory:

apt-get download koolbox koolbox-full

Get:1 https://packages.koolify.ai/apt stable/main amd64 koolbox amd64 1.3.2-1 [79.3 MB]
Get:2 https://packages.koolify.ai/apt stable/main amd64 koolbox-full all 1.3.2-1 [4186 B]
Fetched 79.3 MB in 1s (95.1 MB/s)

That is two files and nothing else: apt-get download does no dependency resolution at all. If your isolated server does not already have PostgreSQL and LibreOffice, they have to come from your own distribution media or local mirror. We could not verify that last part — both verification servers kept an SSH session, so their operating-system repositories stayed reachable, and resolving OS dependencies on a genuinely disconnected host is the one step on this page nobody has measured.

RHEL family. dnf can resolve the whole tree for you, which is a real advantage — and it needs root, and the bundle it produces needs one correction before it will install:

sudo dnf download --resolve --destdir ./koolbox-offline \
  koolbox-1.3.0 koolbox-full-1.3.0            # 146 files, 341 MB, about 6 seconds

# dnf resolves two versions of postgresql from two streams and the local
# install then refuses the whole set. Keep the one that matches
# postgresql-contrib and delete the other:
ls postgresql-*.rpm
rm -f postgresql-13.23-6.el9_8.x86_64.rpm      # keep 13.22, it matches -contrib

146 files is about 341 MB to carry across, and roughly 1.1 GB once installed — the two numbers sit next to each other in dnf's own transaction summary and are easy to mix up:

Transaction Summary
==============================================================================
Install  145 Packages

Total download size: 339 M
Installed size: 1.1 G

Then copy the files across by whatever transfer method your organization approves, and install from them locally. Debian and Ubuntu:

sudo apt-get install -y ./koolbox_*.deb ./koolbox-full_*.deb

This is silent — no warnings at all, 16 to 18 seconds, verified with the Koolify host blocked outright. What does warn is the step before it, if you refresh your package lists on a host that cannot reach the repository:

W: Failed to fetch https://packages.koolify.ai/apt/dists/stable/InRelease  Could not connect to packages.koolify.ai:443 ...
W: Some index files failed to download. They have been ignored, or old ones used instead.

That warning is expected on an isolated server and has no effect on a local install. RHEL family — here the --disablerepo is not optional:

sudo dnf install --disablerepo=koolbox ./koolbox-*.rpm ./koolbox-full-*.rpm

If the KoolBox repository is registered — and it is, on any server installed from it — dnf tries to refresh its metadata before it looks at your local files, and aborts there. On an isolated network that refresh cannot succeed, so disabling that one repository for that one command is what makes the install work.

# Debian / Ubuntu, exit 100
The following packages have unmet dependencies:
 koolbox-full : Depends: koolbox (= 1.2.8-1) but 1.2.7-1 is to be installed
E: Unable to correct problems, you have held broken packages.

# RHEL family
Error:
 Problem: conflicting requests
  - nothing provides koolbox = 1.2.8-1 needed by koolbox-full-1.2.8-1.noarch from @commandline

With the repository still reachable, that same single-package command is not refused — the package manager quietly downloads the missing half over the network, which on a server you believe to be isolated is the opposite of what you want. That is the other reason to carry both files and name both.

Then license the installation with offline activation, and keep it current with offline updates, which from 1.3.0 are a single verified command.

sudo dnf remove koolbox koolbox-full on the RHEL family removes 138 packages and frees about 1.1 GB on 1.3.0 and later, and it leaves PostgreSQL, its data directory, the koolbox role and the koolbox database alone. Measured: no postgresql line appears anywhere in the transaction, and afterwards all four PostgreSQL packages are still installed with the service active and enabled. On Debian and Ubuntu, apt remove never proposed touching the database engine.

What a removal leaves behind, on both distributions:

To remove everything, including the data, that is an explicit decision:

sudo rm -rf /opt/koolbox /etc/koolbox /var/lib/koolbox
sudo rm -rf /var/lib/pgsql        # only if you want the database gone as well

A remove followed by a reinstall preserves everything that was kept, byte for byte: the same configuration file, the same installation identifier, the same admin user, identical row counts and the existing backups. Neither koolboxctl setup nor koolboxctl migrate is needed — the koolbox-full package does both itself.

One more thing worth knowing: installing only koolbox, without koolbox-full, leaves the service stopped on purpose — Service was not running — left stopped. Start it with: systemctl start koolbox.service.

Round figures: one to two minutes for a single-server --full install and well under a minute for an upgrade. Treat those as an indication rather than a guarantee: roughly 80 MB of console has to arrive first, and both of these servers pulled it at 36 to 95 MB/s from a content edge in their own region, so a slower link moves every figure in the table. Where a cell reads —, that operation was exercised on the other distribution only.

The product's own estimate for the console outage during an update — “ roughly 30 to 90 seconds” — is deliberately conservative. Every apply measured here finished in 17 to 25 seconds.

On 1.2.8 and earlier, dnf exits 0 and both packages install, so nothing announces itself as a failure. The only sign is a warning roughly 500 lines before the end of a 560-line run, and the run still signs off cheerfully:

✓ Enabled password authentication for 'koolbox' on koolbox (loopback only).
✗ The database is still not reachable with the configured credentials.
  Verify manually:  PGPASSWORD=… psql -h 127.0.0.1 -U koolbox -d koolbox -c 'SELECT 1'
  Then finish with: sudo koolboxctl migrate
WARNING: local PostgreSQL setup did not complete.
         Then finish with: sudo koolboxctl setup && sudo koolboxctl migrate

The service never starts, so the console does not answer at all — connection refused, not an error page:

$ sudo koolboxctl status
  Application version : 1.2.8
Service
  systemd unit        : koolbox.service
  State               : failed (enabled at boot)
Database
  Connectivity        : unreachable
Health
  No response from http://127.0.0.1:3000/api/health

$ curl -i http://127.0.0.1:3000/api/health
curl: (7) Failed to connect to 127.0.0.1 port 3000: Connection refused

The cause is that RHEL 9 ships PostgreSQL 13, whose default password_encryption is md5, while those releases wrote scram-sha-256 into pg_hba.conf. The role, the database and both extensions were created correctly; only the two ends disagreed about the hash, so authentication could never succeed. Debian and Ubuntu ship PostgreSQL 15 or 16, where scram-sha-256 is already the default, which is why this was confined to the RHEL family.

Upgrading repairs it on its own. The 1.3.x package raises the cluster setting, re-hashes the role's password to match the file it already has, verifies the connection and starts the service — no manual SQL, nothing to type in. Reproduced twice from a genuine 1.2.8 failure, in 22 seconds:

sudo dnf upgrade koolbox koolbox-full     # this alone usually fixes it
sudo koolboxctl status                    # confirm: reachable / active

# only if the service is still down:
sudo koolboxctl setup && sudo koolboxctl migrate

Upgrading KoolBox unknown → 1.3.0
Added new setting: UPDATE_MANIFEST_URL
✓ Merged 1 new setting(s) into /etc/koolbox/koolbox.env.
Service was not running — left stopped. Start it with: systemctl start koolbox.service

  Running scriptlet: koolbox-full-1.3.0-1.noarch                            2/4
✓ Cluster password_encryption set to scram-sha-256 (was md5).
✓ Re-hashed the password of role 'koolbox' under scram-sha-256.
Database 'koolbox' already exists — left untouched.
✓ Ensured PostgreSQL extensions (unaccent, pg_trgm).
pg_hba.conf already grants scram-sha-256 password access to 'koolbox'.
✓ Verified database connectivity as 'koolbox'.
✓ Configuration complete.
Starting koolbox.service to apply schema changes...
✓ Service is ready (version 1.3.0, schema 1.3.0).

$ sudo koolboxctl setup
✓ Cluster password_encryption set to scram-sha-256 (was md5).
✓ Re-hashed the password of role 'koolbox' under scram-sha-256.
Database 'koolbox' already exists — left untouched.
✓ Ensured PostgreSQL extensions (unaccent, pg_trgm).
pg_hba.conf already grants scram-sha-256 password access to 'koolbox'.
✓ Verified database connectivity as 'koolbox'.
✓ Configuration complete.

$ systemctl is-active koolbox
failed

$ sudo koolboxctl migrate
Starting koolbox.service to apply schema changes...
✓ Service is ready (version 1.3.0, schema 1.3.0).

# last resort, only if you cannot upgrade off 1.2.8
sudo -u postgres psql -c "ALTER SYSTEM SET password_encryption = 'scram-sha-256';"
sudo systemctl restart postgresql
DBPASS=$(sudo sed -n 's/^DB_PASSWORD=//p' /etc/koolbox/koolbox.env | tr -d '"')
sudo -u postgres psql -c "ALTER ROLE koolbox WITH PASSWORD '$DBPASS';"
sudo koolboxctl setup && sudo koolboxctl migrate

On a koolbox-full install, the package manager starts the console while it is setting up the koolbox package — before LibreOffice has been unpacked. So a brand-new server logs this even though LibreOffice is installed a few seconds later:

[KoolBox] LibreOffice not found — document generation will output DOCX only (no PDF conversion)
[KoolBox]   Ubuntu/Debian: sudo apt install libreoffice-core libreoffice-writer

One restart is all it needs, and the log then says so:

sudo systemctl restart koolbox

[KoolBox] LibreOffice detected: LibreOffice 24.2.7.2 420(Build:2) — PDF document generation available

Do not install LibreOffice again in response to that first message — it is already there. If PDFs still come out as DOCX after a restart, see Documents come out as DOCX.

In a browser, go to:

http://YOUR-SERVER-IP:3000

Replace YOUR-SERVER-IP with your server's address. On a server on your own network, hostname -I prints it and the first address shown is usually the right one.

Sign in with the credentials that are the same on every new installation. The form labels the first field Email, not Username:

Email     admin@local.koolbox
Password  ChangeMe123!

1. 1
   Click your name at the bottom of the left sidebar. A centered My Account dialog opens, with Appearance, Change Password, Enable 2FA and Sign Out.
2. 2
   Choose Change Password.
3. 3
   Enter the new password twice — it does not ask for the current one — and confirm.

Strongly recommended for every administrator.

1. 1
   Click your name at the bottom of the sidebar again to reopen My Account.
2. 2
   Choose Enable 2FA. This leaves the console for a dedicated full page at /auth/2fa/setup, laid out like the sign-in screen — that is expected, not a lost session.
3. 3
   Scan the QR code with Google Authenticator, 1Password, Authy, or any other authenticator app. If you cannot scan it, use the Manual setup key shown beside it — but use its copy button rather than typing what you see, as the key is visually truncated in its box.
4. 4
   Click I have scanned the QR code, type the 6-digit code from your app, and click Verify and activate.
5. 5
   Save the eight recovery codes it then shows you, somewhere safe. They come in XXXX-XXXX-XXXX form with Download .txt and Copy all buttons, and are shown only once. Each one can be used a single time to get back in if you lose your authenticator. Then click Continue to dashboard.

Until someone completes or dismisses it, each new administrator account gets a seven-step introduction on sign-in: Welcome, Choose Your Operating Mode, AI Agents & Knowledge Bases, Workflows & Automation, Security & Compliance, Guides & Documentation, and Activate Your License. You can step through it or close it.

The only step that changes how the product behaves is Choose Your Operating Mode:

You can change this at any time afterwards under Administration → Settings → Deployment, without reinstalling anything.

Everything is served from https://packages.koolify.ai. No account, password or token is needed to download — your entitlement is enforced by the license inside the product, not by the download. Every URL listed on this page was fetched during verification and all of them returned 200.

The manifest is the authoritative statement of what the current release is. It carries the version, the release date, the oldest version that can upgrade directly to it, and every artifact with its size and SHA-256 — and its signature is what the offline update path checks before it installs anything.

The recommended way is always through your package manager, because it verifies signatures for you:

sudo apt update && sudo apt install --only-upgrade koolbox koolbox-full
sudo dnf upgrade koolbox koolbox-full

To see what the newest version is before installing it, use the commands under Check whether a newer version exists.

The layout is predictable, so you can fetch a single file over HTTPS if you need to. For a version X.Y.Z:

Example:

curl -fLO https://packages.koolify.ai/apt/pool/main/koolbox_1.3.1-1_amd64.deb

Only x86_64 console packages exist. The arm64 and aarch64 paths hold the meta-package alone, which cannot be installed on its own, so there is no ARM download to find here — see ARM servers.

The repository indexes, which list every available version, are at /apt/dists/stable/main/binary-amd64/Packages and /rpm/x86_64/repodata/repomd.xml.

Packages and repository indexes are signed with Koolify's key. If you installed through apt or dnf, signatures are checked on every download automatically and you need do nothing further. To check the fingerprint yourself:

curl -fsSL https://packages.koolify.ai/koolbox.asc | gpg --show-keys

pub   rsa4096 2026-09-15 [SCEA] [expires: 2031-09-14]
      9F1BA391E54B66E96F25E3E117BB084F403BE624
uid                      Koolify Inc Package Signing <packages@koolify.ai>

The fingerprint must be exactly 9F1BA391E54B66E96F25E3E117BB084F403BE624. It is the same key the installer imports, and the same one dnf offers to import as 0x403BE624.