MultiGPT

Installation

The current version is 0.4.0. Ready-made packages for Debian 13 (amd64) are available from a dedicated apt repository, so updates arrive with `apt upgrade`. If you prefer to build yourself, use `make deb`. After that you can chat using your own API keys.

Status 0.4.0: For every version tag, GitHub Actions builds the package on Debian 13, attaches it to the GitHub release and publishes it in the apt repository (the last three versions). New dependencies are bubblewrap (calculations) plus Pango, harfbuzz and the DejaVu fonts (PDF sheets). Coming from 0.2? Read Updating to 0.3. A test installation on a fresh Debian 13 is still pending, and the Docker route is untested so far. The complete operations guide (with backup) follows with milestone 12.

Requirements

The multi-gpt package ships its own Python environment in /usr/share/python/multi-gpt and is started via systemd. It creates the system user multi-gpt; data lives in /var/lib/multi-gpt. nginx and TLS are part of the package: gunicorn listens on 127.0.0.1 only, with nginx in front of it on the same machine.

1. Add the package source (once):

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://beerlesklopfer.github.io/multi-gpt/apt/multi-gpt.gpg \
  | sudo tee /etc/apt/keyrings/multi-gpt.gpg >/dev/null
sudo tee /etc/apt/sources.list.d/multi-gpt.sources >/dev/null <<'EOF'
Types: deb
URIs: https://beerlesklopfer.github.io/multi-gpt/apt
Suites: stable
Components: main
Architectures: amd64
Signed-By: /etc/apt/keyrings/multi-gpt.gpg
EOF
sudo apt update

The key that signs the repository has the fingerprint 8822 DF96 2A10 31EC AD6A 6F40 3DE7 6675 16FC 28FF (check with gpg --show-keys /etc/apt/keyrings/multi-gpt.gpg).

2. Install:

sudo apt install multi-gpt

Updates then arrive with sudo apt update && sudo apt upgrade. Without the package source you can also use the .deb from the GitHub release (sudo apt install ./multi-gpt_<version>_amd64.deb) or build it yourself in the source folder:

sudo apt install build-essential debhelper dh-virtualenv python3-dev python3-venv
make deb    # the .deb ends up in the parent folder

During installation the following happens:

3. Create the database by hand (only needed if the package could not create it, e.g. because PostgreSQL was not running during installation):

sudo -u postgres createuser multi-gpt
sudo -u postgres createdb -O multi-gpt multi-gpt
sudo -u postgres psql -d multi-gpt -c 'CREATE EXTENSION IF NOT EXISTS vector'

4. Check the configuration: in /etc/multi-gpt/.env, adjust DATABASE_URL if needed. Then run sudo systemctl restart multi-gpt.

5. Create the first administrator (and catch up on the schema if the automatic migration did not run):

sudo mgpt-ctl migrate
sudo mgpt-ctl createsuperuser

mgpt-ctl is a wrapper around Django’s manage.py that runs as the multi-gpt user with /etc/multi-gpt/.env. mgpt-ctl migrate can safely be run again at any time. All commands are listed in the wiki: mgpt-ctl (German).

MultiGPT is then reachable at https://<hostname>/. curl -k https://<hostname>/healthz/ shows whether the app is running (-k only with the snakeoil certificate).

6. Set up document search (optional): in the admin under “Dokumente (RAG)” → “Einstellungen”, choose an embedding model (locally e.g. nomic-embed-text via LM Studio) and check it with “Speichern und Embedding testen”; for scanned PDFs choose the OCR method (olmOCR via LM Studio or Tesseract) and check it with “Speichern und OCR testen”. The guide is in the wiki: RAG einrichten (German); folders from the server or NAS are covered in wiki: Verzeichnisquellen (set RAG_SOURCE_ROOTS in /etc/multi-gpt/.env for this).

7. Set up web search (optional): run a SearXNG in the home network, enter its address in the admin, check it with “SearXNG testen” and then switch web search on. The guide is in the wiki: SearXNG (German).

Runner (optional)

The runner gives models a container on a computer in your home network as a workspace. It is a program of its own (multigpt-runner) and not part of the server installation. On the computer the browser runs on you need Linux (amd64 or arm64) with systemd and rootless Podman. Steps: create a token on the “Runner” page in MultiGPT, download the program there from MultiGPT (with a checksum) and pair it with pair. The steps are in the wiki under Runner.

A note on security: by default the runner’s web ports (24080 and 24443) are reachable by the whole home network without any login. If you do not want that, set MGPT_EXPOSE_BIND=127.0.0.1 (details in the wiki).

Updating to 0.3

The package migrates the database itself on every update. When updating from 0.2 to 0.3.x, a few extra steps are needed once by hand (they are also listed in debian/NEWS):

1. Update the package (this pulls in bubblewrap, Pango, harfbuzz and DejaVu) – with the package source from option 1 sudo apt update && sudo apt upgrade, otherwise:

sudo apt install ./multi-gpt_<version>_amd64.deb

2. Let MultiGPT detect the models’ capabilities. Existing models have “tools” set to “no” and would otherwise not be offered web search, page fetching, document tools, calculations or PDF sheets:

sudo mgpt-ctl guess_capabilities            # preview
sudo mgpt-ctl guess_capabilities --apply    # save

Alternatively in the admin: “KI-Modelle” → action “Fähigkeiten automatisch erkennen” (detect capabilities). New models get their capabilities automatically. The command never changes the MCP access per model; new local models may only use MCP tools once enabled in the “MCP” column.

3. Re-index your documents so that citations name paragraph and section (and, if enabled, figures are described): in the admin under “Dokumente (RAG)” click “Alles neu indexieren” (re-index everything), or run

sudo mgpt-ctl reindex

4. Check: in the admin under “Chat-Einstellungen” → “Sandbox testen”. If you override the multi-gpt.service unit with a drop-in, add AF_NETLINK to RestrictAddressFamilies= or leave out RestrictNamespaces=.

All admin commands and options are described in the wiki: mgpt-ctl (German).

Option 2: Docker

For systems without apt. The image builds and installs the same Debian package; compose.yaml adds PostgreSQL with pgvector as a second service. Configuration comes from .env in the project folder (at least SECRET_KEY, FIELD_ENCRYPTION_KEY, ALLOWED_HOSTS, POSTGRES_PASSWORD).

docker compose build
docker compose up -d db
docker compose run --rm web mgpt-ctl migrate
docker compose run --rm web mgpt-ctl createsuperuser
docker compose up -d

Note: the Docker route has not been tested yet.

Option 3: Development with make

The Makefile is the interface for development. It requires a local PostgreSQL with pgvector.

make db-create install migrate user dev