Kubuno - Core

The heart of Kubuno - a self-hosted, libre (AGPLv3) cloud platform, a sovereign alternative to Google Workspace and Microsoft 365.

The core is the platform's "operating system": it provides the infrastructure (auth, database, events, storage, reverse proxy, WebSocket, module lifecycle, administration console) that independent modules (drive, calendar, mail, photos, office, chat…) rely on to run.

---

Screenshots

Why Kubuno?

• Modular architecture - each module (drive, calendar, mail, office, photos…) is a separate process that connects to the core at startup. The core proxies its routes, distributes events and manages its lifecycle; nothing is hard-wired.
• Your data, your rules - fully self-hosted, no third-party service required, no telemetry.
• One binary, three database engines - the same server runs on PostgreSQL, MySQL/MariaDB or SQLite, the engine being chosen at run time from the connection URL. An instance - or a single module - can be migrated from one engine to another from the administration console, and several instances can share one database server thanks to a configurable schema prefix.
• Guided first run - a fresh instance opens on a setup assistant that asks for the database and the first administrator: there is no default password.
• Built-in marketplace - browse the official catalogue and install modules at runtime from the admin console, or offline from the command line (kubuno modules:install <file>.kbpkg). Modules ship as self-contained Kubuno packages (.kbpkg) the core unpacks itself, identically on Linux, Windows and macOS.
• Secure by default - JWT + HttpOnly refresh tokens with rotation, no access token in any script-readable cookie (images, media, downloads and sockets use short-lived signed tickets bound to one session, app and address - see AUTH.md), Argon2id, AES-256-GCM with a data key separate from the signing secret, account lockout and a self-hosted sign-in CAPTCHA after repeated failures, a tamper-evident (HMAC-chained) administrative audit trail, anti-DDoS rate budgets per IP and per user, signed module-to-core authentication, and a seccomp sandbox that forbids process execution inside modules.
• A complete administration console - directory (users, groups, organisational units, target audiences, buildings and resources, directory policy), LDAP / Active Directory and OpenID Connect sign-in, per-unit settings with inheritance and locks, security dashboard, alert centre, automation rules, content detectors, printable reports, backups (whole database, compressed, restorable), data migration from other servers, data export, domains, public holidays, themes and native HTTPS (TLS certificates, ACME).
• Fast and lean backend - Rust + Axum; the database also serves as the event bus and the job queue, with no Redis or extra broker.
• Runtime-loaded frontend - the React 19 host loads modules at runtime via ESM import maps and shared singletons (@kubuno/sdk, @kubuno/ui), without ever naming a module statically, so every app shares one consistent shell.
• Packaged themes (skins) - themes are importable .zip bundles that restyle the whole platform or targeted modules with CSS variables, stylesheets and (admin-trusted) scripts; several themes ship with the core. See THEMES.md.
• Cross-module labels and @mentions - user-owned labels attach to items of any module (files, tasks, events…) and can be shared; typing @ in any text field suggests people from the instance directory.
• Voice search - a microphone in the search bar, backed by the self-hosted speech-to-text service.
• i18n - 13 languages, RTL included.

Architecture

┌──────────────────────────────────────────────────────────┐
│  Frontend host (React 19 / Vite)                         │
│  - shell, auth, admin console, registries, import map    │
│  - loads /modules/<id>/entry.js at runtime               │
├──────────────────────────────────────────────────────────┤
│  Core (Rust / Axum)            ← THIS REPO               │
│  auth · events · storage · proxy · websocket · modules   │
│  PostgreSQL · MySQL/MariaDB · SQLite (schema `core`)     │
├──────────────────────────────────────────────────────────┤
│  Modules (separate processes, dedicated repos)           │
│  drive · calendar · mail · photos · office · chat · …    │
└──────────────────────────────────────────────────────────┘

This repository contains:

Component	Path	Role
kubuno-core	server/	Server application (bin kubuno-core) and administration CLI (kubuno)
kubuno-db	common/kubuno-db	Database foundation: one binary over PostgreSQL / MySQL-MariaDB / SQLite - shared
kubuno-storage	common/kubuno-storage	Storage abstraction (local filesystem; S3 declared, not implemented yet) - shared
kubuno-seccomp	common/kubuno-seccomp	Execution sandbox (seccomp) - shared
kubuno-modauth	common/kubuno-modauth	Signed module ↔ core authentication - shared
kubuno-mcp	common/kubuno-mcp	MCP server building blocks - used by the core
Web host	web/	React shell + shared libraries @kubuno/sdk, @kubuno/ui, @kubuno/drive
Migrations	server/migrations/	Core database schema
Themes	web/themes/	Skin themes shipped with the platform (see THEMES.md)

Shared crates are consumed by the module repositories via tagged git dependencies; the shared frontend libraries are published to npm under the @kubuno/* scope.

Modules

Each app lives in its own repository (kubuno/<module>) and ships its own .kbpkg package:

	Module	Repository	Description
	Drive	kubuno/drive	Files: upload, sharing, search, remote mounts
	Office	kubuno/office	Office suite: documents, spreadsheets, presentations, projects, diagrams, data, maths, script, whiteboard
	Calendar	kubuno/calendar	Calendars, events, CalDAV, scheduling
	Mail	kubuno/mail	Multi-account email client (IMAP/SMTP)
	Chat	kubuno/chat	Messaging, calls and meetings
	Contacts	kubuno/contacts	Address book, groups, CardDAV
	Tasks	kubuno/tasks	Tasks, sub-tasks, Kanban boards, CalDAV VTODO
	Notes	kubuno/notes	Markdown notes, checklists, notebooks, backlinks
	Forms	kubuno/forms	Forms and surveys, responses, analytics
	Photos	kubuno/photos	Photo gallery: albums, timeline, sharing
	Media	kubuno/media	Streaming: Watch (films, series) and Listen (music)
	Books	kubuno/books	Library of books, comics and eBooks
	PaintSharp	kubuno/paintsharp	Creative suite: raster, vector, 3D, video, animation, PDF, fonts
	Wiki	kubuno/wiki	Personal and shared wikis
	Forum	kubuno/forum	Discussion boards with moderation
	App	kubuno/app	Visual no-code application builder
	Flow	kubuno/flow	Visual workflow automation
	Code	kubuno/code	Collaborative web IDE with Git
	Keestore	kubuno/keestore	Password manager (KeePass 4 .kdbx)
	Maps	kubuno/maps	Self-hosted maps, routes, places
	Assistant	kubuno/assistant	Self-hosted AI assistant (local models)
	Speech-to-Text	kubuno/stt	Self-hosted speech recognition for voice search
	P2P NAS	kubuno/p2pnas	Encrypted, self-healing peer-to-peer storage

Install with Docker

The fastest way to self-host Kubuno (core + all modules) is the all-in-one Docker image, published as ghcr.io/kubuno/kubuno:

git clone https://github.com/kubuno/docker && cd docker
cp .env.docker.example .env     # set POSTGRES_PASSWORD, KUBUNO_JWT_SECRET, KUBUNO_INTERNAL_SECRET
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
# → http://localhost:8080
#   A fresh instance greets you with the setup assistant: it asks for the database
#   and the first administrator, so YOU choose the password. There is no default.

Prefer building the image yourself? Run docker compose up --build. The full guide, configuration, module selection and CI live in kubuno/docker.

Native packages (Linux · Windows · macOS)

The core ships as native packages, each installing the server, the frontend host, the database migrations and the bundled themes, and registering Kubuno as a managed system service:

Platform	Format	Script	Service
Debian / Ubuntu	.deb	build_deb.sh	systemd
Fedora / RHEL / openSUSE	.rpm	build_rpm.sh	systemd
Windows 10/11 / Server	.exe (NSIS installer)	build_windows.sh	Windows service (WinSW)
macOS (Apple Silicon)	.pkg	build_macos.sh	launchd

Tagged releases (v*) attach all of them to the corresponding GitHub Release via CI (build.yml for the .deb, dist.yml for RPM / Windows / macOS). The only runtime prerequisite is a reachable database server - PostgreSQL 16 or MySQL / MariaDB - or none at all with SQLite. Full details and per-platform notes: PACKAGING.md.

Modules are not system services: they install as .kbpkg packages into the core, from the Marketplace or with the CLI:

sudo kubuno modules:install calendar-<version>-<os>-<arch>.kbpkg
sudo kubuno modules:list

Administering from the command line

The kubuno command also administers the directory from the server itself - for scripts, headless installs, or when no browser is at hand. It runs the very same operations as the administration console (same password policies, quotas, guards and audit entries, recorded with the "system" origin):

sudo kubuno users:create --email alex@example.org --name "Alex Martin" --generate-password
sudo kubuno users:list --org-unit Support --inactive
sudo kubuno users:password alex@example.org --generate-password --require-change
sudo kubuno users:unlock alex@example.org          # forget failed sign-ins
sudo kubuno groups:add-member Accounting alex@example.org
sudo kubuno org-units:create Marketing --parent Kubuno

Every command has --help; listings accept --json. See man kubuno for the full reference (users:*, groups:*, org-units:*, db:*, auth:recover…).

Build & development

Requirements: Rust ≥ 1.82, Node.js ≥ 24, and PostgreSQL 16, MySQL/MariaDB or SQLite.

# Backend (core)
cargo build --release --bin kubuno-core

# Frontend host
cd web && npm ci && npm run build

# Dev (backend + frontend together)
make dev

# Native packages (see PACKAGING.md)
bash build_deb.sh        # → dist/kubuno-core_*.deb
bash build_rpm.sh        # → dist/kubuno-core-*.rpm
bash build_windows.sh    # → dist/kubuno-core-setup-*.exe   (cross-build, NSIS)
bash build_macos.sh      # → dist/kubuno-core-*.pkg         (on a Mac)

Configuration

Copy config.toml.example → config.toml (every option is documented inline) or override any value with KV_-prefixed environment variables (e.g. KV__DATABASE__SCHEMA_PREFIX). The database engine follows the connection URL: postgres://…, mysql://… or sqlite://….

Tech stack

Rust 2021 · Axum 0.7 · Tokio · SQLx 0.9 (PostgreSQL · MySQL/MariaDB · SQLite) · jsonwebtoken · argon2 · aes-gcm - React 19 · TypeScript · Vite · Tailwind CSS v4 · Zustand · React Query.

Security

Please report vulnerabilities privately - see SECURITY.md.

How the browser authenticates requests it makes on its own (images, media, downloads, event streams, WebSockets) is described in AUTH.md.

Contributing

Contributions are welcome. Please open an issue to discuss any significant change before submitting a pull request.

License

AGPL-3.0-or-later © Kubuno contributors.