Installation & Deployment¶
Deploying Emmu is straightforward. Because Emmu integrates with deep native cybersecurity tools (e.g., Nmap, Subfinder, Ghidra) and complex AI dependencies, Docker is the strictly recommended deployment method. The whole point of the Docker setup is that the only thing you need on the host is Docker + make — no per-machine Go/Playwright/security-tool installs.
1. Prerequisites¶
Before installing Emmu, ensure your environment meets the following requirements: - Git (for cloning the repository). - Docker & Docker Compose (for isolated, reproducible deployments). - uv and Python 3.11+ (only if deploying locally without Docker).
2. Docker Deployment (Recommended)¶
Docker isolates Emmu from your host system while automatically provisioning all necessary penetration testing tools and MCP integrations.
Step 1: Clone the repository and bootstrap local config¶
make setup copies .env.example → .env and mcp.json.example → mcp.json if they don't already exist (it never overwrites existing files). Edit .env and set at least EMMU_UI_PASSWORD — there is no built-in default, and the web UI refuses to start without it.
Step 2: Build and start Emmu¶
This is enough for cloud-LLM users (OpenRouter, Groq, OpenAI, Gemini, etc. configured in.env).
If you want a local model instead, use:
This additionally starts anollama service and pulls phi3:mini on first run.
If you use the CTF Manager's sandbox feature (core/ctf/manager.py), it spins up sibling Docker containers, which requires giving the app container access to the host's Docker socket:
docker-compose.ctf-sandbox.yml for the security tradeoff (root-equivalent host access) before enabling this.
The claude-code/codex/gemini bridges (core/core/bridges/*.py) authenticate either via an API key in .env (ANTHROPIC_API_KEY/OPENAI_API_KEY/GEMINI_API_KEY, billed per-token) or, if you'd rather use an existing Claude Pro/Max, ChatGPT, or Google subscription, by sharing your host's already-logged-in CLI session:
claude once, codex login, gemini auth login) — see docker-compose.bridge-auth.yml, which only shares the specific credential file for CLIs you've actually enabled there.
If you're actively editing templates//static/ and want changes to appear without rebuilding or restarting:
core/ui.py) picks up the change on your next page refresh.
[!NOTE] Once the containers are running, the Web Management UI will be accessible at
http://localhost:5000.
Project-level skills (see skills.sh) for the claude-code/codex/gemini-cli bridges are installed automatically as part of the image build (make skills runs inside the Dockerfile) — no separate step needed for Docker deployments.
Other useful targets: make logs, make shell, make down, make test. Run make build-ctf-sandbox once if you want the CTF sandbox image (emmu-ctf-sandbox) built locally.
[!NOTE] The vendored
cai/framework (Alias Robotics' Cybersecurity AI engine) has its own separatecai/dockerized/andcai/.devcontainer/assets. Those belong tocai's own upstream development workflow, not Emmu's deployment — you don't need them to run Emmu.
3. Local Deployment (Advanced/CLI Only)¶
If you prefer to run Emmu directly on your host (e.g., within Kali Linux), you must manually manage your Python environment and binary dependencies. Emmu uses uv as its dependency manager (a single lockfile pins both Emmu's and the vendored cai framework's dependencies together).
Step 1: Install dependencies¶
Step 2: Install Skills¶
Emmu's skills/ directory (the emmu-pro bridge skills plus ~90 security-technique skills) is installed via skills.sh (npx skills), which writes them project-locally (.claude/skills/, .agents/skills/) rather than into your home directory:
This requires Node.js/npx on the host. See the skills target in the Makefile if you want to see or customize exactly what it installs and where.
[!WARNING] If you are running Emmu locally inside Windows WSL, you may encounter timeouts when the system sleeps. To keep the LxssManager alive, run the following in an elevated Windows command prompt:
reg add "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\LxssManager" /v "AutoStartService" /t REG_DWORD /d 1 /f
Next Steps¶
Once the platform is installed, proceed to the Environment & Configuration guide to connect Emmu to your preferred AI models (Groq, OpenRouter, Gemini) and MCP servers.