Documentation/Deployment/On-Prem Add-On Packages

On-Prem Add-On Packages

Add live database connectors, the integrations catalog, or a self-hosted AI agent to an on-premise Supero backend — each ships as a separate package that stays off until it is installed and licensed.

Overview

An on-premise Supero backend runs a fixed core system by default. Three optional capabilities — live database connectors, the integrations catalog, and a native AI agent — ship as separate packages that stay off until you explicitly install and license them. This page is for operators who already have the core on-premise backend running and want to add one or more of these capabilities to it.

Add-on package	License feature	What it adds
supero-connectors	connectors	Live BYODB connectors — read and sync external databases and warehouses
supero-tenant-services	tenant_services	The integrations catalog, shown in the dashboard as Integrations — email, SMS, chat, and directory-provider connections
supero-ai-agent	ai_agent	A native chat/agent runtime that can converse with and act on your app data, using an LLM provider you configure yourself

ℹ️ Each add-on is independent

The three packages install, license, and start independently of each other and of the core backend. Installing one grants nothing on its own — see the next section for the second requirement that turns it on.

⚠️ App generation stays SaaS-only

supero-ai-agent adds only the runtime agent. Generating new apps, schemas, UI, and workflows — the app-building experience in the dashboard — is not part of this package and has no on-premise equivalent. Keep building apps in the hosted dashboard, then deploy them to whichever target you prefer.

Why "installed" is not the same as "enabled"

An add-on only runs when two independent things are both true: its package is installed on this host, and your signed license explicitly grants it. Installing the .deb by itself grants nothing — a package with no matching license entry stays dark.

•Installed — the add-on's package has been unpacked onto this host, so its code physically exists. Not installed means there is nothing to run.
•Licensed — your signed license's feature list names the add-on, and this host's MAC address is on that license's allow-list.

Check both layers at any time:

bash

sudo supero addons list

ADDON            INSTALLED  LICENSED   ACTIVE
connectors       yes        yes        active
tenant-services  no         no         -
ai-agent         no         no         -

💡 Use sudo to check licensing

The signed license file is readable only by root and the Supero service user. Without sudo, the LICENSED column shows a question mark instead of yes or no — that means the CLI couldn't read the license to check, not that licensing failed.

Prerequisites

•The core on-premise backend (supero-core) must already be installed and running — each add-on package depends on it and reuses its service user, its /etc/supero configuration directory, and its license verification.
•The host must run Python 3.10 — each add-on ships a self-contained virtual environment built against that version, and the package itself pins it as a dependency.
•A signed license whose feature list includes the add-on(s) you want, issued for this host's MAC address(es).

Collect this host's MAC addresses and send them to Supero when requesting or renewing a license:

bash

supero license macs

You'll receive a .lic file back that lists your granted add-on features and allow-lists those MAC addresses.

Install, license, and start an add-on

The three steps below can happen in any order — installing the package and installing the license don't depend on each other — but an add-on only starts once both are in place.

1. Install the add-on package

This is an offline install — no package index is contacted.

bash

sudo apt install ./supero-connectors_1.0.0-1_amd64.deb
# or: sudo dpkg -i ./supero-connectors_1.0.0-1_amd64.deb && sudo apt -f install

2. Install the license that grants it

bash

sudo supero license install /path/to/your.lic
sudo supero license status
# confirm the feature list now includes 'connectors'

3. Start the add-on

This enables the add-on boot-persistently. It refuses to start if the license doesn't grant it.

bash

sudo supero addons start connectors

4. Verify

bash

sudo supero addons list

💡 Order is flexible

You can install the package before or after the license. supero addons list always shows exactly which of the two layers is still missing.

Connectors: one extra driver for SQL Server and Fabric

The bundled connector environment already includes drivers for PostgreSQL, MySQL, and Oracle — Oracle runs in thin mode, so no separate system package is required. All three work as soon as supero-connectors is installed and licensed.

⚠️ SQL Server and Microsoft Fabric need one extra system package

Microsoft distributes its ODBC Driver 18 under its own license, so it can't be bundled inside the .deb. Until it's installed on the host, a SQL Server or Fabric connection test degrades to "verified when discovery runs" instead of connecting live.

bash

# Debian/Ubuntu — requires network access to packages.microsoft.com
curl -fsSL https://packages.microsoft.com/keys/microsoft.asc \
    | sudo gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg
echo "deb [signed-by=/usr/share/keyrings/microsoft-prod.gpg] https://packages.microsoft.com/debian/11/prod bullseye main" \
    | sudo tee /etc/apt/sources.list.d/mssql-release.list
sudo apt-get update && sudo ACCEPT_EULA=Y apt-get install -y msodbcsql18 unixodbc

PostgreSQL, MySQL, and Oracle connectors need none of this.

Native AI agent: bring your own LLM

supero-ai-agent adds a native chat/agent runtime over your app's data. It never calls a Supero-hosted model — you configure it with your own LLM provider credentials, or point it at a fully self-hosted local model for an air-gapped install with no external network calls at all.

Configure the add-on through its setup step, which prompts for your provider and API key — or, for an air-gapped install, the URL of your self-hosted model — and writes them to the add-on's environment file. For the exact variable names and the list of supported providers and local-model runtimes, follow the AI Agent add-on install guide included with your license.

💡 Air-gapped installs

Point the add-on at a self-hosted model on your own network and it makes no external calls at all — the chat/agent runtime, your data, and the model all stay inside your environment.

After configuring the add-on, restart it so it picks up the change:

bash

sudo supero addons restart ai-agent

Operations and uninstall

Once an add-on is installed and licensed, manage it like any other on-premise service:

Action	Command
Overview (installed x licensed)	supero addons list
Detail plus a health check	supero addons status <name>
Start (enable and run)	sudo supero addons start <name>
Stop (disable and halt)	sudo supero addons stop <name>
Restart (e.g. after an env edit)	sudo supero addons restart <name>
Logs	journalctl -u supero-<name> -n 100

<name> is one of:

•connectors
•tenant-services
•ai-agent

Uninstalling an add-on

bash

sudo supero addons stop connectors
sudo apt remove supero-connectors   # removes the code; keeps /etc/supero/connectors.env
sudo apt purge supero-connectors    # also removes the env file and install tree

Troubleshooting

Symptom	Cause	Fix
supero addons start reports the add-on as installed but not licensed	Your license's feature list doesn't include this add-on	Install a .lic that grants it, then re-run supero license status to confirm
The add-on's service won't stay running	Not licensed, or this host isn't on the license's MAC allow-list	Check supero license status; confirm this host's MACs with supero license macs and request a license that covers them
Install warned that the bundled environment failed a smoke import	Host Python isn't 3.10 — an ABI mismatch with the bundled environment	Install Python 3.10 on the host, or use a host image that matches the pin
LICENSED still shows no after installing a .lic	The stored license was hand-edited, or the .lic didn't install cleanly	Add-on features are only recognized from a verified signed license file — reinstall the .lic rather than editing any stored copy of it

Next Steps

•On-Premise Deployment — install and initialize the core backend these add-ons attach to.
•Connectors Overview — what live connectors do once supero-connectors is enabled.
•Database Connectors — supported databases and warehouses, and how discovery and sync work.
•Managed Integrations & Provider Catalog — the integrations catalog that supero-tenant-services unlocks on-premise.

← PreviousOn-Premise Deployment Next →Workspace, Domains & Tenants

On this page