Kuzzle: A self-hosted TypeScript backend for APIs and realtime data

Why Kuzzle targets repeated backend work

Kuzzle addresses the part of application development that appears in many products regardless of the interface: storage access, API exposure, realtime events, user sessions, security rules, and reusable server-side behavior. The repository describes Kuzzle as a generic backend whose building blocks can be used by web applications and complex IoT networks. That makes it relevant to teams that would otherwise assemble these features separately for every application.

The target audience is broader than a single client framework. Kuzzle is described as suitable for Web, Apps, Mobile, and IoT, while its API is intended to be multi-protocol. The repository also points to SDKs for client applications, but the README does not enumerate the supported language versions or SDK installation commands. The server is written primarily in TypeScript, and the package is named `kuzzle`.

Kuzzle does not present itself as a frontend framework or as a narrow database library. It is a backend platform with an application model, controllers, persisted data, searching, authentication, permissions, and realtime notifications. This distinction matters when choosing it. A project that only needs an HTTP route and an in-memory response may find Kuzzle heavier than necessary, while a product needing several backend capabilities may gain a shared foundation.

The server, protocol, and storage path

The documented architecture places Kuzzle beside Elasticsearch and Redis. The Docker Compose file runs a Kuzzle node from the `kuzzleio/kuzzle-runner:24-trixie-slim` image and mounts the repository into `/var/app`. Its environment points the storage engine at `http://elasticsearch:9200`, while the internal cache and memory storage point to the `redis` service. The service waits for both dependencies to become healthy before starting.

The server exposes the Kuzzle API on port `7512` and MQTT on port `1883`. The README's first application registers a controller named `greeting`, with an action named `sayHello`. The action reads `request.input.args.name` and returns a greeting string. This is the clearest visible data flow in the repository: a client sends an API action, Kuzzle dispatches it to the registered controller, and the handler produces the response.

Kuzzle also documents persisted data, advanced searching, pub/sub, database notifications, authentication, permissions, and an integrated framework for business features. Those capabilities indicate a backend with shared runtime services rather than a standalone HTTP handler. The README does not document the complete data model, replication design, deployment topology, or recovery procedure, so those details require separate confirmation before production adoption.

Kourou, Docker Compose, and the first Kourou application

The README identifies Kourou as the easiest way to start a Kuzzle application. The following command scaffolds a project named `playground`:

kourou app:scaffold playground

The documented output says to enter the generated directory and start the stack with Docker Compose. The next command starts Kuzzle's services, including Kuzzle, Elasticsearch, and Redis:

kourou app:start-services

The generated project can then run its application inside Docker with this command:

npm run docker:dev

After startup, the README states that Kuzzle is listening on port `7512`. The Docker Compose file maps `"7512:7512"`, `"1883:1883"`, and `"9229:9229"` from the container. The port mapping is useful when checking connectivity, but it also means that a local deployment is not limited to the API. MQTT and the debug port are exposed by the development Compose file.

The repository's `package.json` also defines `npm run dev` as `tsx watch start-kuzzle-dev.ts`, and the Compose command uses `npm run dev`. This distinction matters for operators. The README's application flow uses `npm run docker:dev` inside the generated project, while the repository-level development service uses the Kuzzle runner container and the repository's own scripts.

Registering and calling a Kuzzle controller

A first API action can be added in the generated `app.ts` file. The README uses `Backend`, registers a controller called `greeting`, defines a `sayHello` action, and starts the application. The complete example is:

import { Backend } from 'kuzzle';

const app = new Backend('playground');

app.controller.register('greeting', {
  actions: {
    sayHello: {
      handler: async request => `Hello, ${request.input.args.name}`
    }
  }
});

app.start()
  .then(() => {
    app.log.info('Application started');
  })
  .catch(console.error);

The controller name and action name form the request path. The README gives this browser request:

http://localhost:7512/_/greeting/say-hello?name=Yagmur

It also gives a Kourou invocation using the action's camelCase spelling:

npx kourou greeting:sayHello --arg name=Yagmur

The HTTP example and the Kourou example are useful checks because they exercise two client paths. A successful response should contain a greeting based on the supplied name. The README does not document the exact response envelope for this action, so applications should use the response format documented for their Kuzzle version rather than assume that the entire response equals the handler string.

Operational dependencies and development exposure

Kuzzle's documented startup path is not a single process. It depends on Elasticsearch for the storage engine and Redis for internal cache and memory storage. The Compose configuration uses health conditions for both services, which can prevent the Kuzzle node from starting before those dependencies are ready. This arrangement is appropriate for a backend with persisted data and realtime behavior, but it creates more deployment work than a single-process service.

The development Compose file also sets MQTT development mode to `false` while enabling MQTT. The repository exposes the MQTT port and the Node debug port on the host. Those settings are visible in the development configuration, not necessarily in a production deployment. A production operator should not treat the presence of those mappings as a production security policy.

The README says Kuzzle can be deployed on premises and describes production use, but it does not give a production hardening checklist, backup procedure, cluster sizing guidance, or upgrade rollback instructions. It also does not state how Elasticsearch and Redis versions are selected for a production release. Those omissions are material for teams considering Kuzzle as a stateful service.

A practical alternative to assembling the backend yourself

The direct alternative is to assemble the same functions from separate components: an HTTP or realtime server, a database client, a search engine, an authentication layer, a permission system, and application-specific publish and subscribe handling. That approach can fit a team that already has these services, standard deployment tooling, and a clear need for a small API surface. It avoids adopting Kuzzle's application framework and its coordinated Elasticsearch and Redis setup.

Kuzzle takes a different approach. It provides one backend abstraction with controllers, stored data, searching, authentication, permissions, realtime notifications, and client-facing API concepts. The application code shown in the README registers domain behavior as a controller rather than wiring every route directly to infrastructure. That can reduce repeated application setup when several client types need the same backend contract. The trade-off is that the team must understand Kuzzle's API model and operate more than one infrastructure dependency.

The README does not provide a direct migration guide from a competing backend or a benchmark comparing Kuzzle with an alternative. Therefore, the choice should be based on feature fit and operating constraints, not on a claim that one approach is faster or more reliable in every workload.

Maintenance, upgrades, and the Apache-2.0 license

The repository is not archived. Its last push was on 2026-10-15, so maintenance claims should be tied to that date and the listed releases rather than to an implied guarantee of future support. The repository lists `v2.59.0` on 2026-10-01 and `v2.60.0-beta.1` on 2026-10-12. The package version in `package.json` is `2.59.0`.

That release pattern includes both stable and beta releases, but the README excerpt does not document the compatibility policy between them. It also does not specify migration steps for upgrading Kuzzle, Elasticsearch, Redis, or the generated application. The presence of `.migration/` in the repository layout indicates migration-related content, but the README excerpt does not explain its contents. An upgrade plan should therefore be established from the release notes and migration documentation for the selected version.

Kuzzle is published under the Apache 2 License, identified in the README as `Apache 2 License` and in the repository as `LICENSE.md`. The license permits use and modification under its stated terms, but the project is not a guarantee of support, service availability, or compatibility with a particular deployment. Commercial support plans are mentioned separately from the open-source license.

Editorial conclusion

Adopt Kuzzle when a self-hosted backend with API controllers, persisted data, realtime features, authentication, and client SDK support fits your application. Do not choose it for a small service that needs only a conventional HTTP framework. Verify first whether Elasticsearch and Redis fit your deployment model, whether the generated Docker stack meets your operational requirements, and whether Kuzzle's API and permission model match your client architecture.

Frequently asked questions

Official sources

1. kuzzleio/kuzzle on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases