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

Akka installs into your AI coding harness through that harness’s own plugin mechanism. Select your harness:

  • Claude Code

  • Gemini CLI

  • Codex CLI

  • Cursor, VS Code + Copilot

/plugin marketplace add akka/ai-marketplace
/plugin install akka@ai-marketplace
/reload-plugins

Can’t add the marketplace? Clone the repository and add it as a local marketplace instead:

git clone https://github.com/akka/ai-marketplace.git
/plugin marketplace add /path/to/ai-marketplace
gemini extensions install https://github.com/akka/ai-marketplace
codex plugin marketplace add akka/ai-marketplace
codex plugin add akka@akka

Codex exposes the commands as skills. Where this documentation shows /akka:specify, use the akka-specify skill (@akka-specify, or ask Codex to run it).

akka specify init --agent cursor

Use --agent vscode-copilot for VS Code with Copilot. Cursor has no slash commands — the Akka tools are available over MCP; where this documentation shows /akka:specify, ask the agent to run that step.

This installs the Akka commands and registers the Akka MCP server, giving your harness the full Akka toolset (CLI, MCP server, AI coding assistant, and project scaffolding).

Configure your environment

/akka:setup

This ensures the Akka CLI is installed, Java and Maven are available, and your Akka download token is configured.

Choose your mode

The Akka Specify plugin runs in one of two modes:

  • Enforced (the default) makes you define "done" as machine-checkable exit conditions before code is written, and gates shipping until they are met — a cleaner, auditable result.

  • À la carte lets you run the specification commands individually, with nothing blocking you — faster and lighter.

New installs start in Enforced mode. Switch at any time:

/akka:mode enforced
/akka:mode a-la-carte

See Choosing your mode for the trade-offs. Then build your first agent with the Spec-first hello agent tutorial, which walks the same build in either mode.

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