Self-host Kisuno

What you need

For Kisuno you need an Ubuntu machine with Docker Engine and Compose v2, a DNS record pointing to it and an API key for your model gateway. The stack runs entirely on this single host, because the computing load of the language models sits with the inference provider.

Server and system requirements

The minimum is 2 vCPU, 4 GB RAM, a 40 GB disk and Ubuntu 22.04 LTS. For production use we recommend 4 vCPU, 16 GB RAM and a 200 GB disk on Ubuntu 24.04 LTS; the breakdown by team size is in the table below. The hardened code sandbox additionally requires nested virtualisation.

Under load, practically only the memory of the chat application grows, while CPU utilisation stays close to zero. The images take up around 5 to 6 GB once and are shared between instances on the same machine. After that it is mainly the uploads that grow: the first limit in operation is disk space.

What you do not need

• No Kubernetes. Docker Compose is the supported architecture; a Helm chart is not included.
• No GPU for the app tier. GPU hardware is only needed by those who also want to run language models locally.
• No account with us. The installation runs without registration, without a licence key and without a licence server.
• No hyperscaler and no managed database. Any Ubuntu VM will do; database and search index run in the same stack.

Installation in three steps

Installing Kisuno consists of two scripts and one entry in the .env. On a machine where Docker is already running, the first step is not needed.

Step 1: prepare the server

The GitHub repository is coming soon. Anyone who wants to start today can request access to the managed instance via the form. The commands show what the installation looks like afterwards: clone the repository, change into the distribution directory, run the preparation script.

cd distribution
./setup-server.sh

The script is idempotent and installs Docker Engine including Compose v2 from the official Docker source, because the Ubuntu package docker.io does not ship Compose v2. It also sets up log rotation, firewall rules for ports 22, 80 and 443, swap, time zone and automatic security updates. Then log in again once.

Step 2: install the stack

./install.sh --profiles production

The installer checks Docker and Compose v2, creates the .env from the template, generates all secrets, sets up data directories and the sandbox network, pulls the images and starts the stack. The production profile includes the reverse proxy, which obtains the TLS certificate automatically.

Step 3: enter model access

# .env
MODEL_API_KEY=<euer-api-key>

docker compose up -d

Without a key the stack still starts, but the chat reports a missing API key. Access is freely selectable, because Kisuno talks to any OpenAI-compatible gateway. In the managed instance we offer the current models from OpenAI (ChatGPT) and Anthropic (Claude); they run in the AWS data centre in Frankfurt. AWS is a US company, so the US CLOUD Act applies even with servers in Frankfurt, and we say so openly. For customers with higher data-protection requirements, open frontier models such as GLM, Kimi and DeepSeek are available, operated by European companies on servers in Europe; the US CLOUD Act does not apply there. When self-hosting you choose every provider in this chain yourself and enter your own endpoint.

Which services make up the stack

The stack consists of one docker-compose.yml; several services sit behind optional profiles and only start when you switch them on. Every service is a well-known open source project and can be inspected, replaced or switched off individually.

The chat application is based on LibreChat under the MIT licence and provides the interface, accounts, conversations, file uploads and the model connection. Kisuno keeps this part close to upstream so that the project’s security updates remain adoptable.

MongoDB stores conversations, accounts, roles and settings, as a container in the same stack and on your disk. There is no external database service to which content could flow away.

Meilisearch provides full-text search across your own conversations. The index is local and can be rebuilt; Meilisearch telemetry is disabled out of the box.

The RAG API with pgvector is optional and is added through the filesearch profile. The RAG API embeds files that users upload into the chat and returns the relevant passages to the model when it answers.

The MCP gateway sits between the chat application and every connected system and decides per tool call whether it is permitted. Evaluation follows this order: individual user, role, group, server default. Every call is logged, and if the check fails, access is denied.

The admin panel is the interface for users, roles, groups, access rules, audit log and budget. It is part of the stack, listens locally only and is reachable from outside exclusively through the reverse proxy.

The code sandbox executes the code generated by the model, turning a request into a real file you can download. It is placed alongside as its own Compose stack and connected via a dedicated Docker network. Two backends are available: a lightweight one as the default and a hardened one based on a microVM, which requires nested virtualisation on the host. An egress proxy with an allow list is in progress.

SearXNG provides web search from your own stack, without an account at a search service. To be honest about it: SearXNG passes the search terms on to external search engines, without disclosing the user’s identity. Conversations and files do not leave the machine.

Caddy terminates TLS, obtains the certificates automatically as soon as the DNS record points to the machine, and is the only service on ports 80 and 443. Variants are included for operation behind a WAF or with an internal certificate authority.

Three operating models, one architecture

There are three operating models and only one architecture: self-operated, in your cloud, optionally through your IT service provider, or managed by us. The stack is the same in all three cases. The only differences are who holds root, who manages the keys and who runs updates and backups.

Self-operated

You run the machine, hold root, manage your keys and handle updates and backups yourself. The software costs nothing; a support subscription is optional. This model is the benchmark: what an external administrator can bring up in two commands also carries the other models.

In your cloud

Kisuno runs on any Ubuntu VM, in your own data centre just as well as at a Swiss or European cloud provider. There is no tie to a hyperscaler. IT service providers hosting for their customers use the same architecture: one stack per customer.

Managed by us

We take care of installation, updates, backups and monitoring and operate the instance in ISO 27001-certified data centres run by Green in Lupfig, Switzerland. The certificates are held by Green, not by Kisuno; an ISO 27001 certification of Kisuno itself is in progress.

Several instances on one machine

The tenant boundary is the Compose stack, not the VM: each instance has its own database, its own search index, its own uploads, its own secrets, its own Docker network and its own code sandbox. For small teams, three to five instances may therefore share the same VM.

What may be shared are the Docker images and a common reverse proxy. What is never shared are database, uploads, secrets, sandbox network and the model provider’s key: a shared key makes consumption per tenant impossible to attribute, and a shared sandbox network removes the separation exactly where third-party code runs.

How updates work and what matters in operation

Updates are reproducible because the application image is pinned to a digest rather than to a moving tag, and the remaining services run on fixed versions. A release of Kisuno is therefore a tested combination of application image and services, and two instances on the same machine may run different versions.

git pull
./backup.sh backup
./install.sh --migrate

The --migrate option leaves the .env untouched and rebuilds the in-house services. A backup belongs before every update, followed by a short functional test. Rolling back is done via the previous version of the Compose file.

Two things matter in day-to-day operation: the log rotation that setup-server.sh sets up, and disk space with an alert from 70 per cent utilisation. Recurring questions about operation, updates and backups are answered in the frequently asked questions.

One script for backup, restore and migration

A single script covers backup, restore and server migration: backup.sh creates an archive from the database dump, the .env and uploaded files, and restores it as well. A migration is therefore a backup on the old server, copying the archive, and a restore on the new one.

./backup.sh backup            # Archiv erzeugen
./backup.sh list              # vorhandene Archive
./backup.sh restore <archiv>  # ersetzt die Datenbank, fragt vorher nach

The archive contains secrets and conversations and is stored with restrictive file permissions. It never belongs in a repository and never unencrypted in someone else’s cloud. The search index is not backed up, because it can be rebuilt from the database.

The most expensive mistake during a migration is to have the encryption keys regenerated instead of carrying them over from the old .env. All credentials stored in the database then become unreadable. With carried-over values, the migration remains a maintenance window of 15 to 30 minutes.

Two rules from practice: mirror the backup target off the machine and test the restore once.

Licence: what MIT means in practice

Kisuno will be released under the MIT licence shortly; the underlying chat application LibreChat is already under it today. Self-hosting is free, from a single user and without registering with us. What that means in detail, and why it is the decisive difference in the comparison with other platforms:

• No seat limit. Whether 3 or 300 people work on the instance makes no difference to the licence.
• No mandatory branding. Name, logo and colours are configuration, including for commercial use.
• No feature gating. Permission management, audit log, budgets and system connections all come from the same open source.
• Open source code. The LibreChat base is publicly viewable today; stack, scripts and services will be published under MIT shortly and will then be viewable, forkable and verifiable instead of resting on a promise.

Commercially, we sustain the model through operation and support, not through licences. That is why the path from managed operation back to self-hosting is open as well: the same architecture, the same archive.

Frequently asked questions about self-hosting