Containerized dev environment

If you want to try Akka without installing Java, Maven, and the Akka CLI on your machine, the Akka dev container gives you a ready-to-use environment inside Docker. It bundles everything you need: Java 21, Maven, the Akka CLI, and pre-cached SDK dependencies. You can start building in minutes.

The dev container is ideal for getting started quickly. For long-term development, we recommend installing the tools directly on your machine. See Tutorials for the standard setup path.

Prerequisites

Set environment variables

The Akka download token is required. AI provider keys are optional and only needed if you plan to build agent samples.

export AKKA_RESOLVER_TOKEN=<your-token>       # required
export GOOGLE_AI_GEMINI_API_KEY=<your-key>    # optional, for agent samples
export ANTHROPIC_API_KEY=<your-key>           # optional, for agent samples
export OPENAI_API_KEY=<your-key>              # optional, for agent samples

Create a project and start the container

  1. Use the Akka CLI to create a new project from a sample:

    akka code init --name helloworld-agent --repo akka-samples/helloworld-agent.git

  2. Start the dev container with the project directory mounted:

    docker run -d --name akka-dev \
  -v "$(pwd)/helloworld-agent":/workspace \
  -p 9000:9000 \
  -p 9889:9889 \
  -e AKKA_RESOLVER_TOKEN \
  -e GOOGLE_AI_GEMINI_API_KEY \
  -e ANTHROPIC_API_KEY \
  -e OPENAI_API_KEY \
  registry.akka.io/akka-dev-container:latest

    This starts the container in the background with two forwarded ports:

    • localhost:9000 for your Akka service endpoint

    • localhost:9889 for the Akka local console

Run the service

All build commands run inside the container using docker exec. Your files are on the host. You edit them with your normal editor, and the container picks up changes immediately through the bind mount.

Run the service:

docker exec -w /workspace akka-dev mvn compile exec:java

Once the service is running, test it from your host:

curl -i -XPOST http://localhost:9000/hello \
  --header "Content-Type: application/json" \
  --data '{"user": "alice", "text": "Hello, I am Alice"}'

Start the local console

The Akka local console provides a web UI for inspecting your running service. Start it with:

docker exec -t -w /workspace akka-dev akka local console --bind-address 0.0.0.0

Then open localhost:9889 in your browser.

How it works

Host-mounted workspace

Your project directory is bind-mounted to /workspace in the container. You edit files on the host, the container runs builds. No file syncing needed.

Pre-cached dependencies

Most Akka SDK dependencies are baked into the image, significantly reducing download times on first run.

Forwarded ports

Port 9000 (Akka service) and 9889 (local console) are exposed to your host machine.

Next steps

Once you are comfortable with Akka, install the tools directly on your machine for the best development experience: