Kern

One place for your team's work — issues, conversations, documents and people.
Open source. Self-hosted. Yours.

kernaio.com

---

Most teams pay for four tools that do not talk to each other. An issue tracker. A chat app. A wiki. Something for HR. Every link between them is a copy-paste.

Kern is one application instead. An issue can have its own channel. A message can become an issue. The people in your HR records are the people in your projects. Nothing is synchronised, because nothing is separate.

You run it on your own machine. Your data stays there.

What works today

Kern is pre-1.0 and in active development. This list is what actually runs, not what is planned.

Area	State
Accounts, workspaces, roles and permissions	Working
Issues and projects — list, board, detail, queries, cycles, time tracking	Working
Chat — channels, direct messages, threads, reactions, presence	Working
Notifications across every workspace you belong to	Working
Files, search, audit log, workspace settings	Working
Email the platform sends (per-workspace providers, delivery log, bounces)	Working
Documents several people edit at once (Quire) — spaces, page tree, version history, published sites	Working
People (HR) — directory, org chart, leave, attendance, approvals	Working
Inventory — the asset register, custody, repairs	Working
Billing — plans, subscriptions, Stripe checkout (off by default when self-hosted)	Working
Instance updates — a signed release feed, and an instance that upgrades itself inside a window	Working
Personal mail inbox (your own IMAP account)	Not built
Drive, calendar, recruiting, CRM, automation, calls, AI	Not built

Everything above is one workspace or many, in English, German, Persian or Arabic, left-to-right or right-to-left, in light or dark.

Install Kern

Goal: run Kern on your own server and open it in a browser.

You need:

• An x86-64 Linux machine with Docker 24 or newer and the Compose plugin.
• 4 GB of RAM and 20 GB of disk. The whole stack idles under 700 MB; the rest is the room Postgres uses to cache your data while your team works.
• A domain name, or an IP address for a machine on your network.

The published images are amd64, so an arm64 server needs images built for it. Full table: Requirements.

1. Run the installer

curl -fsSL https://raw.githubusercontent.com/KernAIO/app/main/selfhost/install.sh -o install.sh
bash install.sh

The installer asks for your domain, an admin email address and an admin password — on the terminal, which is why it is downloaded first rather than piped into bash. It writes them to ~/kern/.env along with freshly generated secrets. Docker with the Compose plugin has to be installed already.

Expected result: the installer prints the address of your new Kern.

2. Sign in

1. Open the address the installer printed.
2. Sign in with the admin email address and password you chose.

Expected result: Kern opens on your first workspace.

If your server runs Coolify

Do not run the installer. Coolify already holds the ports, issues the certificate and keeps the environment, so Kern ships a Compose file written for it in selfhost/coolify/. Add it as a Docker Compose resource, give the caddy service your domain, and deploy. Every secret is generated by Coolify.

Full steps: Install on Coolify.

If the installer cannot reach Docker

Problem: the installer stops with Docker is required.

Cause: Docker is not installed, or your user cannot talk to the Docker daemon.

Solution:

1. Install Docker from https://docs.docker.com/get-docker/.
2. Run docker ps to confirm it answers.
3. Run the installer again.

Develop Kern

Goal: run every Kern service on your own machine, with hot reload.

You need:

• Node 24 and pnpm 10.
• Docker, for Postgres and the other infrastructure.
• Roughly 5 GB of disk space.

1. Clone and install

git clone https://github.com/KernAIO/app
cd app
pnpm setup

pnpm setup clones every Kern repository into repos/ and installs all dependencies at once.

Expected result: repos/ contains fifteen directories — kernel, the eight module-* repositories, core, chat, mail, collab, shell and docs. Run node scripts/repos.mjs to print the same list.

2. Start the infrastructure

pnpm infra

This starts Postgres, NATS, Valkey, MinIO and Mailpit in Docker.

Expected result: docker ps lists five containers with names beginning kern-dev.

3. Start everything

pnpm dev

Each service creates its own database tables the first time it starts, so there is nothing to migrate by hand.

Expected result: the app is at http://localhost:5173, and the services are at :4000 (core), :4100 (chat), :4200 (mail) and :4300 (collab).

Work on the interface without any of that

cd repos/shell
pnpm dev:mock

This runs the whole interface against demo data held in memory. It needs no database and no services, and it is what the end-to-end tests run against.

If Postgres will not start

Problem: pnpm infra fails, or a service cannot connect to the database.

Cause: something else is already listening on port 5432 — often a Postgres you installed yourself.

Solution:

1. Set KERN_PG_PORT=5433 in .env.
2. Point DATABASE_URL at whichever Postgres you mean to use.
3. Run pnpm infra again.

How Kern is put together

Every feature is a module. A module owns its own database schema, its own API and its own screens, and it declares what it contributes. A workspace can switch any module off, and every trace of it disappears — no navigation, no routes, no notifications.

The modules Kern ships with are written against the same public interfaces anyone else would use. If you can build a module, you can build a feature that sits beside ours as an equal.

Repository	What it is
app	This one: how to install Kern, the documentation, and the workspace that links the rest
shell	Every screen people use
core	Accounts, workspaces, roles, permissions, notifications, files and search
chat	Conversations, and the connection that keeps everything live
mail	Email leaving Kern, and replies coming back
collab	Documents several people edit at the same time
kernel	The libraries every service and module is built on
module-template	Apache-2.0 starting point for a module: a whole working one — contract, server, schema, screens and strings
module-tracker, -chat, -quire, -hr, -mail, -billing, -inventory	The features Kern ships with — one repository each, built the way yours would be
docs	The documentation site
brand	The logo, and the rules for using it

Read docs/ARCHITECTURE.md for how the pieces fit, and docs/PLAN.md for where this is going.

Contribute

Start with CONTRIBUTING.md. It covers the repository layout, the tools, and what a change has to pass before it lands.

Kern is built in the open. Every commit is public the moment it is pushed. That is why the rules in CLAUDE.md apply to everyone — people and coding agents alike.

Licence

Two licences, split at one line. The framework is Apache-2.0. The product is AGPL-3.0-only.

You may run Kern for any purpose, for as many people as you like, and change anything in it. If you give other people a changed Kern — as a download or over a network — you share those changes under the AGPL. That is the whole of the obligation.

Writing a module? You only touch the framework — @kernhq/kernel, @kernhq/contracts, @kernhq/sdk, @kernhq/ui and the template are all Apache-2.0 — so your module is yours. Keep it private, keep it closed, sell it. No permission needed.

Selling hosted Kern? Allowed. Publish your changes and use your own name — the code is open, the name is not. TRADEMARK.md covers that, including how to use the name if you would rather partner than compete.

Full map: LICENSING.md · reasoning: ADR 0005 · contributions are accepted under the CLA.