Set up your dev env

There are three ways to set up an Akka development environment. Pick the one that fits how you want to work. Each path is self-contained and lists its own prerequisites.

Every tutorial and sample links back to the path it needs, so you set up once here and refer to it from everywhere else.

Set up your AI harness

Install the Akka Specify Plugin in your AI coding assistant. From there the plugin installs and configures the rest of the tools for you.

Prerequisites

  • A supported AI coding assistant (Claude Code recommended; Akka supports 30 AI-assist tools).

  • An Akka download token (free).

Install the plugin

In Claude Code, install the Akka plugin from the AI Marketplace:

/plugin marketplace add akka/ai-marketplace
/plugin install akka@ai-marketplace
/reload-plugins
If you cannot add the marketplace, clone the plugin repository and add it as a local marketplace: git clone https://github.com/akka/ai-marketplace.git, then /plugin marketplace add /path/to/ai-marketplace.
Not using Claude Code? See Spec-driven development for plugin installation instructions for your tool.

Configure your environment

/akka:setup

This ensures the Akka CLI is installed, Java and Maven are available, and your Akka download token is configured. Once it completes, you are ready to build — continue with Spec-first hello agent.

Set up your env without AI

Install the tools directly on your machine. Use this path if you do not want an AI harness, or your AI-assist tool does not support plugins.

Prerequisites

Install the Akka CLI

In case there is any trouble with installing the CLI when following these instructions, please check the detailed CLI installation instructions.
Linux

Install the akka CLI using the Debian package repository:

curl -1sLf \
  'https://downloads.akka.io/setup.deb.sh' \
  | sudo -E bash
sudo apt install akka
macOS

The recommended approach to install akka on macOS, is using brew

brew install akka/brew/akka
Windows

Install the akka CLI using winget:

winget install Akka.Cli
By downloading and using this software you agree to Akka’s Privacy Policy and Software Terms of Use.

Verify that the Akka CLI has been installed successfully by running the following to list all available commands:

akka help

Create a project

Create a new project from a sample and start building:

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

To use spec-driven development without an AI plugin, use akka specify init <dir> instead — see Spec-driven development. Then continue with Code-first hello agent.

Containerized dev environment

Run Akka inside a pre-built Docker container. Nothing but Docker is installed on your machine — the container bundles Java 21, 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.

See also