Kitten

Checked against the 16 November 2026 release of Kitten (API version 1).

What’s a technical manual?

A technical manual documents the internals of a system.

Kitten’s technical is both a walkthrough and reference of how Kitten works in technical detail. Think of it as the equivalent of those old-school factory service manuals you’d get for cars (and even computers) back in the day.

If you want to help improve Kitten, you can use it to quickly get a conceptual model of how it works.

If you just want to use Kitten to build Small Web apps and sites, start with the reference guide and tutorials. Then, if you do decide to work your way through this manual also, you’ll be rewarded with a deeper understanding of how Kitten works under the hood.

Where things are

A map of the Kitten repository and what each part does.

Environment variables

Environment variables used by Kitten, the launcher, and related scripts.

Exit codes

Kitten’s exit codes and the exit codes of the update guard.

Kitten’s operating model

The rules that shape Kitten.

Initialisation

From the installer and the launcher to the command-line interface and the Kitten Server.

Request handling

The order in which the Kitten Server handles a request, from middleware and routes to files and errors.

Rendering

How Kitten source becomes HTML.

Live pages and components

Page routes, live pages, and the socket routes that connect them.

Data

Persistence in Kitten.

Sessions and sign-in

How Kitten stores sessions, and how identity and sign-in work.

Uploads

How Kitten parses request bodies and stores uploaded files.

Kitten’s internal web app

The web app that every Kitten server serves alongside yours.

Logging and debugging

Sectioned logs, the interactive shell, and debugging recipes.

Production

How Kitten runs as a systemd service.

Updates

How Kitten updates itself and the app it serves in one transaction.

Build and release

Building and releasing Kitten, the release checklist, and types.

Testing

Kitten’s test suites and the npm scripts that run them.

Questions?

Contact Aral on the fediverse. To report a bug or propose a change to Kitten, open an issue.

Like this? Fund us!

Small Technology Foundation is a tiny, independent not-for-profit.

We exist in part thanks to patronage by people like you. If you share our vision and want to support our work, please become a patron or donate to us today and help us continue to exist.