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

import akka.actor.{ Actor, ActorSystem, Props }
import akka.kernel.Bootable

case object Start

class HelloActor extends Actor {
  val worldActor = context.actorOf(Props[WorldActor])

  def receive = {
    case Start => worldActor ! "Hello"
    case message: String =>
      println("Received message '%s'" format message)

class WorldActor extends Actor {
  def receive = {
    case message: String => sender() ! (message.toUpperCase + " world!")

class HelloKernel extends Bootable {
  val system = ActorSystem("hellokernel")

  def startup = {
    system.actorOf(Props[HelloActor]) ! Start

  def 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.HelloKernel

Use Ctrl-C to interrupt and exit the microkernel.

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