Process overview

Specify service interface and domain model

The main components of a Kalix service are:

  • Stateful Entities

  • Stateless Actions

  • Views, which return the state of multiple instances of a stateful entity.

The service interface and the domain data model (for Entities), are contained in individual .proto files, as gRPC descriptors. Separating the service interface and data model in different files allows you to evolve them independently.

The gRPC definitions in .proto files describe the external interface, messages, and events. From the .proto files, the gRPC CLI (protoc), generates the code framework for remote procedure calls, data access, and serialization. Take a look at Writing gRPC descriptors for more information about defining messages and events.

Kickstart a project using the JavaScript code generation tool.

Implement components

Stateful services can implement Value Entity, Event Sourced Entity, or Replicated Entity components. Stateless services implement Actions. Typically, a stateful service should only have one Entity type, but can also include Actions.


Actions are stateless functions that can be triggered by gRPC or HTTP calls. They can also subscribe to published events, and they can send commands to other services based on the events they receive. For more information about writing actions see Implementing Actions.


Stateful services encapsulate business logic in in Value Entities, Event Sourced Entities, or Replicated Entities. At runtime, command messages invoke operations on Entities. A command may only act on one Entity at a time.

To update multiple Entities from a single command use forwarding and effects.

For more information see Forwarding and effects in JavaScript.

Services can interact asynchronously with other services and with external systems. Event Sourced Entities emit events to a journal, to which other services can subscribe. By configuring your own publish/subscribe (pub/sub) mechanism, any service can publish their own events and subscribe to events published by other services or external systems.

For more details and examples take a look at the following topics:

Create unit tests

It is good practice to write unit tests as you implement your services. The JavaScript kickstart codegen project packages Mocha and Chai and is configured for test-driven development.

Package service

Use a Docker image to package your service and any of its dependencies. See the following pages for more information:

Run locally

You can test and debug your services by running them locally before deploying to Kalix.

Deploy to Kalix

After testing locally, deploy your service to Kalix using the CLI or the Console. The following pages provide information about deployment: