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

  • Antigravity (agy) 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

agy (Antigravity CLI) has officially replaced Google’s Gemini CLI.

agy plugin 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).

/akka:setup and akka specify init both scaffold into the current directory. Create a fresh folder first (mkdir my-akka-project && cd my-akka-project) so nothing existing is overwritten. See Spec-driven development for the full lifecycle.

Harness support matrix

Not every AI coding harness has a first-class Akka install. The matrix below groups harnesses by which install path applies.

Harness Path Install target

Claude Code

Plugin

/plugin marketplace add akka/ai-marketplace then /plugin install akka@ai-marketplace

Claude Tag (Slack)

Plugin

Claude Code manifest in akka/ai-marketplace

OpenAI Codex CLI

Plugin or CLI init

codex plugin marketplace add akka/ai-marketplace, or akka specify init --agent codex + Register the Akka MCP server

Cursor

Plugin or CLI init

Cursor Marketplace (search "Akka") or akka specify init --agent cursor

Kiro (AWS)

Plugin

Kiro Powers (search "Akka")

GitHub Copilot (VS Code)

CLI init

akka specify init --agent vscode-copilot

GitHub Copilot in Visual Studio 2022

CLI init

akka specify init --agent vs-copilot

GitHub Copilot coding agent

CLI init + off-workspace MCP

akka specify init --agent copilot-agent (registers MCP in repo/org settings on github.com)

Antigravity (agy)

Plugin

agy plugin install https://github.com/akka/ai-marketplace

Roo Code

CLI init

akka specify init --agent roo

Trae

CLI init

akka specify init --agent trae

Factory Droid

CLI init

akka specify init --agent factory

Cognition Devin

CLI init

akka specify init --agent devin

JetBrains Junie

CLI init

akka specify init --agent junie

Warp

CLI init + off-workspace MCP

akka specify init --agent warp (registers MCP via Warp Settings → MCP)

Google Jules

CLI init + off-workspace MCP

akka specify init --agent jules (registers MCP in Jules workspace settings)

Zed

CLI init + off-workspace MCP

akka specify init --agent zed + Zed’s context_servers block (see Register the Akka MCP server)

Aider

CLI + AGENTS.md + manual MCP

akka specify init (neutral) + Register the Akka MCP server

Sourcegraph Cody

CLI + AGENTS.md + manual MCP

akka specify init (neutral) + Register the Akka MCP server

Claude.ai chat (with Projects)

CLI + AGENTS.md + manual MCP

Paste the install playbook at akka.ai into the project’s custom instructions; MCP is admin-gated

Any harness not listed

CLI + AGENTS.md + manual MCP

akka specify init (writes AGENTS.md + .mcp.json); if the harness’s MCP path is elsewhere, see Register the Akka MCP server

Installation path

  • Plugin (bundle install) — the harness reads Akka’s plugin bundle from akka/ai-marketplace and registers the full toolset (slash commands where supported, MCP server, SDK context).

  • CLI init (akka specify init --agent <harness>) — no bundle for this harness; the Akka CLI writes the harness’s own native rules or instructions file plus its MCP config.

  • CLI + AGENTS.md + manual MCP — fallback for harnesses without a plugin bundle and without a CLI agent profile. Install the CLI, register the MCP server by hand, keep AGENTS.md at the project root.

akka specify init with no --agent flag writes a portable install (AGENTS.md + .mcp.json) and auto-detects the harness from Tier 1 marker files in the target directory (.claude/, .cursor/, .roo/, .trae/, .factory/, .devin/, .junie/, .vscode/mcp.json) — a single unambiguous marker overrides the default. Verified --agent profiles that install a per-harness commands / rules surface: claude-code, cursor, vscode-copilot, vs-copilot, roo, trae, agy. AGENTS.md-native profiles that write a project MCP file: generic, factory, devin, junie. AGENTS.md-native profiles whose MCP registration lives outside the workspace: warp, jules, zed, copilot-agent, codex (each prints the vendor-specific registration hint). Scaffolded (installs neutral files with a warning until the vendor publishes verifiable rules-file / MCP-config paths): kilo, cline, replit, jetbrains-copilot, xcode-copilot, nvim-copilot. See akka specify init for the full list. The canonical AGENTS.md template is published at doc.akka.io/_attachments/AGENTS.md so akka specify init and manual setups reference the same file.

For AI-driven installs, the human-facing entry point is akka.ai — paste "install Akka from akka.ai" into any supported harness and it walks the flow above.

Update the plugin

Keep the Akka Specify Plugin up to date with the latest commands and fixes.

Update the Akka Specify Plugin through that harness’s own plugin mechanism. Select your harness:

  • Claude Code

  • Antigravity (agy) CLI

  • Codex CLI

  • Cursor, VS Code + Copilot

/plugin marketplace update
/plugin update akka
agy plugin update ai-marketplace
codex plugin marketplace upgrade ai-marketplace

Cursor and VS Code + Copilot use the Akka CLI directly over MCP, with no plugin marketplace to update. Update the Akka CLI itself to get the latest version; see Install the Akka CLI for the upgrade command on your platform.

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:

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

  • Enforced makes you define "done" as machine-checkable exit conditions before code is written, and gates shipping until they are met — a cleaner, auditable result. Opt in when you want that rigor.

New installs start in À la carte mode. Switch at any time:

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

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 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.

See also