Setting up a local development environment

This section covers how to set up your local development system, both to develop Cloudstate services, and to deploy and run on Akka Serverless. You will need the following:

  • The Cloudstate CLI: akkasls.

  • Docker: for building and publishing your images.

  • A container repository service to push your docker images into so that Akka Serverless can retrieve them.

Cloudstate CLI

Download and install the appropriate version of the Cloudstate CLI for your platform.

  1. Download the CLI for your platform from one of the the following links:

  2. Optionally, you can verify the integrity of the downloaded files using the SHA256 checksums.

  3. From a command/terminal window, navigate to the location of the download.

  4. Extract the archive:

    tar xzf akkasls_linux_amd64.tar.gz
    mv akkasls ~/.local/bin
    Mac OSX
    tar xzf akkasls_darwin_amd64.tar.gz
    mv akkasls /usr/local/bin

    Using a tool available on your system, such as winzip or Cgywin, extract your downloaded archive to a convenient location.

  5. Add the akkasls executable location to your path.

    This prevents the need to enter the full pathname when using the command.

    For any Mac OS X users who run version 10.15 ( “Catalina” ) or newer, you might need to perform an additional step due to security measures. Once the binary has been downloaded and uncompressed as shown in the previous steps, execute the following command before executing akkasls for the first time:

    Assuming that the akkasls binary is now available at a location specified in your $PATH variable.

    xattr -d `which akkasls`
  6. To verify that the Cloudstate CLI has been installed successfully, enter:

    akkasls version

    The current version should print to the screen.

  7. To see help and a list of available commands, enter:

    akkasls help


If you have Docker version 19.03 or higher, skip to [Container repository]. You can check by entering docker version in a command window.

Install Docker using the procedures for your OS:


Follow the Docker instructions:


Follow the Docker instructions:


Follow the Docker instructions:


Install from the command line or use the Docker installer:

brew cask install docker       # Install Docker
open /Applications/  # Start Docker



Follow the Docker Install instructions:


Download and run the Docker installer from:

Container registry

You can use any private or public repository, such as Google’s Container Registry or Docker Hub. Any registry you use must be accessible by Akka Serverless so that it can retrieve the images to deploy.

What’s next