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.

The Akka Microkernel is included in the Akka download found at downloads.

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

Put your application jar in the deploy directory to have it automatically loaded.

To start the kernel use the scripts in the bin directory, passing the boot classes for your application. Example command (on a unix-based system):

bin/akka sample.kernel.hello.HelloKernel

Use Ctrl-C to interrupt and exit the microkernel.

On a Windows machine you can also use the bin/akka.bat script.

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

 *  Copyright (C) 2009-2013 Typesafe Inc. <http://www.typesafe.com>
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() {

Distribution of microkernel application

To make a distribution package of the microkernel and your application the akka-sbt-plugin provides AkkaKernelPlugin. It creates the directory structure, with jar files, configuration files and start scripts.

To use the sbt plugin you define it in your project/plugins.sbt:

addSbtPlugin("com.typesafe.akka" % "akka-sbt-plugin" % "2.2.5")

Make sure that you have a project/build.properties file:


Then you add it to the settings of your project/Build.scala. It is also important that you add the akka-kernel dependency. This is an example of a complete sbt build file:

import sbt._
import Keys._
import akka.sbt.AkkaKernelPlugin
import akka.sbt.AkkaKernelPlugin.{ Dist, outputDirectory, distJvmOptions}

object HelloKernelBuild extends Build {
  val Organization = "akka.sample"
  val Version      = "2.2.5"
  val ScalaVersion = "2.10.2"

  lazy val HelloKernel = Project(
    id = "hello-kernel",
    base = file("."),
    settings = defaultSettings ++ AkkaKernelPlugin.distSettings ++ Seq(
      libraryDependencies ++= Dependencies.helloKernel,
      distJvmOptions in Dist := "-Xms256M -Xmx1024M",
      outputDirectory in Dist := file("target/hello-dist")

  lazy val buildSettings = Defaults.defaultSettings ++ Seq(
    organization := Organization,
    version      := Version,
    scalaVersion := ScalaVersion,
    crossPaths   := false,
    organizationName := "Typesafe Inc.",
    organizationHomepage := Some(url("http://www.typesafe.com"))
  lazy val defaultSettings = buildSettings ++ Seq(
    // compile options
    scalacOptions ++= Seq("-encoding", "UTF-8", "-deprecation", "-unchecked"),
    javacOptions  ++= Seq("-Xlint:unchecked", "-Xlint:deprecation")


object Dependencies {
  import Dependency._

  val helloKernel = Seq(
    akkaKernel, akkaSlf4j, logback

object Dependency {
  // Versions
  object V {
    val Akka      = "2.2.5"

  val akkaKernel = "com.typesafe.akka" %% "akka-kernel" % V.Akka
  val akkaSlf4j  = "com.typesafe.akka" %% "akka-slf4j"  % V.Akka
  val logback    = "ch.qos.logback"    % "logback-classic" % "1.0.0"

Run the plugin with sbt:

> dist
> dist:clean

There are several settings that can be defined:

  • outputDirectory - destination directory of the package, default target/dist
  • distJvmOptions - JVM parameters to be used in the start script
  • configSourceDirs - Configuration files are copied from these directories, default src/config, src/main/config, src/main/resources
  • distMainClass - Kernel main class to use in start script
  • libFilter - Filter of dependency jar files
  • additionalLibs - Additional dependency jar files