Reference sections
Reference âș Getting started
Kitten is a little web kit (âkittenâ, get it?) optimised for people (not corporations) who make the new everyday things for themselves and other people â not because they want to become billionaires but because they want to contribute to the common good by helping nurture the Small Web while adhering to the Small Technology Principles.
Kitten features intuitive file system-based routing, HTML and accessibility validation, a built-in object database, WebSockets, zero-code authentication, public-key cryptography, Markdown support, syntax highlighting via highlight.js, semantic styles via Water CSS, and more.
- Linux or macOS.
- Common developer tools and system utilities (
git,tar,tee, andxz).
For production servers, only Linux with systemd is supported.
To install Kitten, either:
đ Clone the Kitten repository and run the
./installscript:git clone https://codeberg.org/kitten/app kitten cd kitten ./installđ Or, copy and paste one of the following commands into your terminal to pipe the installation script into your shell and run it:
wget -qO- https://kittens.small-web.org/install | bashcurl -sL https://kittens.small-web.org/install | bashDownload and view the install script source to verify itâs safe to pipe to your shell.
You can also compare it to the code in the source repository to ensure theyâre the same.
On macOS, you have a couple of manual post-installation steps to perform.
(Detailed instructions on how to carry out the below steps are presented in the installer at installation time.)
You must update your systemâs path with the location of the
kittencommand as ~/.local/bin is not on the path by default on macOS.(You will also have to do this on Linux distributions that donât automatically add this folder to your system path. The installer will prompt you to do this if it detects that this is the case.)
If you want to test peer-to-peer apps locally, you must edit your /etc/hosts file to add Kittenâs localhost aliases (place1.localhost, place2.localhost, âŠ, place4.localhost).
To learn more about building peer-to-peer Small Web apps, see the End-to-end encrypted peer-to-peer Small Web apps tutorial.
If you want to install not the latest version of Kitten but the latest version for a given API version, modify your download command to tack the api version to the URL and to pass it as an argument to the bash script. For example, if you wanted to install the latest Kitten package for API version 1 using CURL, your command would look like this:
curl -sL https://kittens.small-web.org/install/1/ | bash -s -- 1If youâre running an âimmutableâ Linux distribution like Fedora Silverblue, please install Kitten from your host account (instead of from within a container) at least once so Kitten can set unprivileged ports to start from 80 (so it can run without elevated privileges).
You can update Kitten in two ways:
On a development machine, run
kitten update. It installs the newest Kitten release and leaves your apps alone.On a server, Kitten checks for updates itself (see Versioning), and the
kitten updatecommand checks at once, as Check now on the Kitten Settings page does. Both move Kitten and the deployed app together, within the Kitten API version the app declares, and roll back when the new version does not start. Note that thekitten updatecommand runs its own update check beside the serverâs, so while automatic updates are on, use Check now instead.
Kittenâs API version 0 releases (23 April, 9 October, and 21 October 2026) do not automatically update themselves to API version 1. On the 23 April and 9 October releases, the kitten update command moves Kitten to the 21 October release. On the 21 October release, the kitten update command reports that Kitten is up to date. To upgrade to API 1, please run the installer again (curl -sL https://kittens.small-web.org/install | bash).
For more details, please see Upgrading from API version 0 to API version 1.
You run kitten from the command-line (using a terminal app). Switch to a folder that has the content you want Kitten to serve and enter the following command:
kitten
You should see Kitten launch and tell you that itâs serving your site or app at https://localhost.
Youâre not limited to accessing your local machine via https://localhost, either. You can also use any local IP address that itâs accessible from (see Accessing your local machine from other devices on your local area network for more information). You can also use the IP aliases 127.0.0.2 - 127.0.0.4 and localhost aliases (subdomains) place1.localhost - place4.localhost without certificate errors. The latter, especially, are useful when testing the peer-to-peer features of Small Web apps.
Small Web places made with Kitten are meant to be owned and used by one person. Until an identity and secret has been generated for this person, Kitten will display a link to the special page that generates them. (Your secret on a Small Web place never hits the server.) You can also generate this secret from Kittenâs REPL using the .id create command.)
Note that the first time Kitten is run, it will create a TLS certificate authority and add it to your system trust stores as well as to Firefox and Chrome so you can run your development environment from https://localhost to match the deployment environment as closely as possible. Your operating system will ask your permission before allowing this.
By default, Kitten will be as quiet as possible and only surface warnings and errors. If you want more extensive logging, start it with the LOG environment variable set to the log sections you want to see:
LOG=<sections> kitten [path to serve]
Similarly, if you want to see performance statistics, set the PROFILE environment variable to true.