The purpose of the Akka Microkernel is to offer a bundling mechanism so that you can distribute an Akka application as a single payload, without the need to run in a Java Application Server or manually having to create a launcher script.


Akka Microkernel will be deprecated and removed. It will be replaced by using an ordinary user defined main class and packaging with sbt-native-packager or Typesafe ConductR.

To run an application with the microkernel you need to create a Bootable class that handles the startup and shutdown the application.

The code for the Hello Kernel example (see the HelloKernel class for an example of creating a Bootable):

package sample.kernel.hello.java;

import akka.actor.ActorRef;
import akka.actor.UntypedActor;
import akka.actor.ActorSystem;
import akka.actor.Props;
import akka.kernel.Bootable;

public class HelloKernel implements Bootable {
  final ActorSystem system = ActorSystem.create("hellokernel");

  public static class HelloActor extends UntypedActor {
    final ActorRef worldActor = getContext().actorOf(

    public void onReceive(Object message) {
      if (message == "start")
        worldActor.tell("Hello", getSelf());
      else if (message instanceof String)
        System.out.println(String.format("Received message '%s'", message));

  public static class WorldActor extends UntypedActor {
    public void onReceive(Object message) {
      if (message instanceof String)
        getSender().tell(((String) message).toUpperCase() + " world!",

  public void startup() {
    system.actorOf(Props.create(HelloActor.class)).tell("start", null);

  public void shutdown() {

sbt-native-packager is the recommended tool for creating distributions of Akka applications when using sbt.

Define sbt version in project/build.properties file:


Add sbt-native-packager in project/plugins.sbt file:

addSbtPlugin("com.typesafe.sbt" % "sbt-native-packager" % "1.0.0-RC1")

Use the package settings and specify the mainClass in build.sbt file:

import NativePackagerHelper._

name := "hello-kernel"

version := "0.1"

val akkaVersion = "2.3.16"

libraryDependencies ++= Seq(
  "com.typesafe.akka" %% "akka-kernel" % akkaVersion,
  "com.typesafe.akka" %% "akka-actor" % akkaVersion,
  "com.typesafe.akka" %% "akka-slf4j" % akkaVersion,
  "ch.qos.logback" % "logback-classic" % "1.0.7"

mainClass in Compile := Some("akka.kernel.Main")


mappings in Universal ++= {
  // optional example illustrating how to copy additional directory
  directory("scripts") ++
  // copy configuration files to config directory
  contentOf("src/main/resources").toMap.mapValues("config/" + _)

// add 'config' directory first in the classpath of the start script,
// an alternative is to set the config file locations via CLI parameters
// when starting the application
scriptClasspath := Seq("../config/") ++ scriptClasspath.value


Use the JavaServerAppPackaging. Don't use AkkaAppPackaging (previously named packageArchetype.akka_application, since it doesn't have the same flexibility and quality as the JavaServerAppPackaging.

Use sbt task dist package the application.

To start the application (on a unix-based system):

cd target/universal/
unzip hello-kernel-0.1.zip
chmod u+x hello-kernel-0.1/bin/hello-kernel
hello-kernel-0.1/bin/hello-kernel sample.kernel.hello.java.HelloKernel

Use Ctrl-C to interrupt and exit the microkernel.

On a Windows machine you can also use the bin\hello-kernel.bat script.