Autonomous OODA-loop pentesting agent. Hermes brain, Kali + Playwright tools over MCP, ATT&CK as the Orient language.
Configuration (.env)
All keys and credentials live in a .env file at the repo root. It is not versioned (it is in
.gitignore) and is the only place where you put secrets. The template .env.example documents
every variable.
The easiest way to produce a working .env is the installer — it only asks for your OpenRouter key
and auto-generates the two secret tokens:
./install.sh
To do it by hand, copy the template and fill in the values:
cp .env.example .env
Required variables
| Variable | Required | Where to put it / how to get it |
|---|---|---|
OPENROUTER_API_KEY |
Yes | Your OpenRouter API key (the provider of the LLM that reasons the OODA). Create it at https://openrouter.ai/keys and paste it into the .env. Not required in Ollama mode (see below). |
HERMES_API_SERVER_KEY |
Yes | Key for Hermes' API server (min. 8 chars). Generate one with openssl rand -hex 32 and paste it into the .env. It is also the Bearer to pilot Hermes over HTTP. |
VULNERATOR_MCP_INBOUND_TOKEN |
Yes | Inbound Bearer for the vulnerator-mcp front door, which is up by default in streamable-HTTP mode. Generate one with openssl rand -hex 32 and paste it into the .env. The default stack is fail-closed on this: docker compose up aborts without it. It is a separate secret from HERMES_API_SERVER_KEY and gates a different edge. (The local stdio mode for Claude Code / Kiro does not need it.) |
The installer (
./install.sh) fillsOPENROUTER_API_KEYfrom your input and auto-generates bothHERMES_API_SERVER_KEYandVULNERATOR_MCP_INBOUND_TOKENas separate 32-byte hex secrets.
Optional — AWS (cloud collection)
Only needed if you are going to use the cloud collection tools (Prowler / ScoutSuite / Cloudsplaining). If you are not auditing AWS, leave these empty. Use read-only credentials for the account you are AUTHORIZED to audit.
| Variable | Required | Where to put it / how to get it |
|---|---|---|
AWS_ACCESS_KEY_ID |
No | Read-only credential for the account you are AUTHORIZED to audit. |
AWS_SECRET_ACCESS_KEY |
No | Secret for that same credential. |
AWS_SESSION_TOKEN |
No | Only for temporary credentials (STS). |
AWS_REGION |
No | Default region (e.g. us-east-1). |
Optional — model, ports, scoping
| Variable | Required | Where to put it / how to get it |
|---|---|---|
OPENROUTER_MODEL |
No | Overrides the OpenRouter model Hermes reasons with. Empty = the profile default (mistralai/mistral-large-4-0). Caveat: the project uses Mistral Large on purpose because models like Claude (anthropic/*) refuse the authorized-offensive pentest framing (OpenRouter/Anthropic returns "violative cyber content"); overriding with such a model may make the agent refuse to work. |
VULNERATOR_MCP_HOST_PORT |
No | HOST port to publish the vulnerator-mcp streamable-HTTP server. By default it publishes no host port (internal docker network only). Set this and uncomment the service's ports: block in docker-compose.yml to publish on a controlled machine. |
HERMES_API_HOST_PORT |
No | HOST port where Hermes' :8642 API server is published. Empty = 8642. |
KALI_MCP_HOST_PORT |
No | HOST port where kali-mcp is published for host-side inspection. Empty = 8900. |
KALI_ARTIFACTS_TOKEN |
No | Shared token for the Kali artifacts data channel. |
PROWLER_STATUS / PROWLER_REGIONS / PROWLER_SERVICES / PROWLER_TIMEOUT |
No | Scope the Prowler cloud scan. Empty = compose defaults. |
The rest of the .env.example variables come with sane defaults; leave them empty unless you need
to change them.
Local inference with Ollama (optional)
By default Hermes reasons with Mistral Large on OpenRouter. If you prefer to run the model yourself,
point Hermes at an Ollama endpoint (OpenAI-compatible) instead. This is
opt-in and fully controlled from the .env:
| Variable | Required | Where to put it / how to get it |
|---|---|---|
OLLAMA_BASE_URL |
No | Empty = use OpenRouter (default). Set it to an Ollama OpenAI-compatible endpoint to use Ollama instead: http://host.docker.internal:11434/v1 for a local host Ollama, or http://<host>:11434/v1 for a remote one. When set, OPENROUTER_API_KEY is not required. |
OLLAMA_MODEL |
No | The Ollama model name used in Ollama mode, e.g. qwen2.5-coder:32b. |
At startup the stack branches on OLLAMA_BASE_URL: when it is empty the OpenRouter path is used
exactly as before (and a missing OPENROUTER_API_KEY still aborts startup); when it is set, the
startup script runs hermes config set model.provider custom, model.base_url <OLLAMA_BASE_URL>
and model.default <OLLAMA_MODEL>, so Hermes talks to Ollama.
Caveats before you rely on it:
- Context window (hard blocker): Hermes refuses to start against an endpoint serving less than
~64K tokens of context, and Ollama defaults to as low as 4K. Raise it server-side where Ollama
runs with
OLLAMA_CONTEXT_LENGTH=64000(it cannot be raised through the API). - Networking: make Ollama listen on all interfaces (
OLLAMA_HOST=0.0.0.0) so the container can reach it. On Linux, reaching a host-run Ollama relies on theextra_hosts: ["host.docker.internal:host-gateway"]mapping already set onooda-agent(Docker Desktop on macOS/Windows resolveshost.docker.internalautomatically). - Model suitability (experimental): every pentest action routes through MCP, so the model must do reliable tool/function-calling and must not refuse the authorized-offensive pentest framing. Parity with Mistral-Large-on-OpenRouter is not guaranteed — treat local inference as experimental and validate your chosen model before relying on it.