Reference › Technical Manual
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.
- One server, one app, one owner.
- Follow standards and good practices
- Don’t rebuild the platform
- Complexity happens, simplicity you have to fight for
- Peer-to-peer, not centralised.
- Keep development and production as similar as possible.
- Start up (and restart) quickly
- Keep tests running quickly
- Errors are useful and can be acted on
- State lives in the data directory.
- Documentation matters
Initialisation
From the installer and the launcher to the command-line interface and the Kitten Server.
- Installer
- Launcher
- Main process
- Kitten Process Manager
- Loader script
- Kitten bundle
- Main script
- Command-line interface (CLI)
- Kitten commands
- Kitten Server
Request handling
The order in which the Kitten Server handles a request, from middleware and routes to files and errors.
- Request pipeline
- Middleware
- Routes
- The route handler
- Routes added through router
- Files
- Errors and restarts
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.