Containerized env

Run Akka inside a pre-built Docker container. Nothing but Docker is installed on your machine — the container bundles Java 25, Maven, the Akka CLI, and pre-cached SDK dependencies.

Prerequisites

Set environment variables

The download token is required. AI provider keys are optional and only needed for 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. 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 forwards localhost:9000 for your service endpoint and localhost:9889 for the Akka local console.

Run the service

Build commands run inside the container with docker exec; your files stay on the host through the bind mount.

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

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 with docker exec -t -w /workspace akka-dev akka local console --bind-address 0.0.0.0, then open localhost:9889.