Wanaku Configuration

This document provides a comprehensive overview of the configuration options for all components of the Wanaku project.

Described here are both Wanaku-specific configurations, prefixed with wanaku, and relevant Quarkus-specific configurations, prefixed with quarkus.

NOTE

Quarkus is the ultimate source for their descriptions. In case the description here conflicts with the ones from Quarkus, please consider the ones from them as being the actual correct value.

Properties are typically stored in application.properties files within each module and can be set in runtime using -D<property.name>=<value> or by exporting equivalent environment variables (i.e.: PROPERTY_NAME=<value>).

IMPORTANT

Some of the settings can only be set at build time.

Configuration Basics

Wanaku is built on Quarkus, a Java framework that uses application.properties files for configuration. If you are unfamiliar with Quarkus, this section explains how configuration works.

What is `application.properties`?

application.properties is a plain text file containing key-value pairs, one per line. Each line sets a configuration property:

properties

quarkus.http.port=8080
wanaku.service.name=my-tool
quarkus.log.level=INFO

Lines starting with # are comments. Blank lines are ignored.

Where is `application.properties` located?

Each Wanaku component ships with a built-in application.properties file inside its JAR/binary at src/main/resources/application.properties. These files contain sensible defaults and are embedded at build time.

For the main components:

Router Backend: apps/wanaku-router-backend/src/main/resources/application.properties
Tool Services: capabilities/tools/<service>/src/main/resources/application.properties
CLI: apps/wanaku-cli/src/main/resources/application.properties

How to override configuration at runtime

You do not need to modify the built-in files. Quarkus provides several ways to override configuration values when running Wanaku:

1. External `application.properties` file

Place an application.properties file in a config/ directory next to the Wanaku binary. Quarkus automatically reads it and any properties defined there override the built-in defaults:

text

my-deployment/
├── wanaku-router-backend-runner.jar
└── config/
    └── application.properties    ← your overrides go here

You only need to include the properties you want to change, not the entire file.

2. System properties (`-D` flags)

Pass individual properties on the command line using -D:

shell

java -Dquarkus.http.port=9090 -jar wanaku-router-backend-runner.jar

3. Environment variables

Export properties as environment variables. Convert the property name to uppercase, replacing dots (.) and hyphens (-) with underscores (_):

shell

export QUARKUS_HTTP_PORT=9090
java -jar wanaku-router-backend-runner.jar

Priority order

When the same property is defined in multiple places, the following priority applies (highest to lowest):

System properties (-D)
Environment variables
External config/application.properties
Built-in application.properties (inside the JAR)

For complete details, see the Quarkus Configuration Guide.

1. Router Backend

Configuration for the main Wanaku Router Backend (wanaku-router-backend), which orchestrates all services.

General & HTTP

Property	Description
`quarkus.http.port`	`8080` - The primary HTTP port for the router backend.
`quarkus.http.cors.enabled`	`true` - Enables Cross-Origin Resource Sharing (CORS).
`quarkus.http.cors.origins`	A comma-separated list of allowed origins for CORS requests (e.g., for the admin UI).
`quarkus.http.access-log.enabled`	`true` - Enables the HTTP access log for monitoring requests.

Multi-Component Protocol (MCP) Server

Property	Description
`quarkus.grpc.server.use-separate-server`	`false` - The gRPC server shares the main HTTP server, avoiding the need for a separate port. Both router and capabilities use this mode by default.
`quarkus.mcp.server.wanaku-internal.sse.root-path`	`/wanaku-internal/mcp` - The SSE endpoint path for the internal MCP namespace.
`quarkus.mcp.server.ns-*.sse.root-path`	`/ns-*/mcp` - The SSE endpoint paths for the 10 available external namespaces (`ns-1` to `ns-10`).
`quarkus.mcp.server.traffic-logging.enabled`	`true` - Enables logging of all MCP traffic for debugging.
`quarkus.mcp.server.traffic-logging.text-limit`	`1000000` - The maximum length of the body to log for MCP traffic.
`quarkus.mcp.server.server-info.name`	`Wanaku` - The name of the server.
`quarkus.mcp.server.server-info.version`	The version of the server, taken from the project version.
`quarkus.mcp.server.client-logging.default-level`	`debug` - The default logging level for MCP clients.

Authentication & Authorization (OIDC)

Property	Description
`wanaku.http.auth`	`keycloak` - Controls authentication mode. Set to `none` to disable authentication entirely. Also settable via `WANAKU_HTTP_AUTH` environment variable.
`auth.server`	The base address of the Keycloak authentication server (e.g., `http://localhost:8543`).
`auth.proxy`	The public-facing address of the OIDC proxy (e.g., `http://localhost:8080`).
`quarkus.oidc.auth-server-url`	The full URL to the Keycloak realm, derived from `auth.server`.
`quarkus.oidc.client-id`	`wanaku-mcp-router` - The OIDC client ID for the router backend itself.
`quarkus.oidc.application-type`	`hybrid` - Allows the backend to act as both a web app (for the admin UI) and a service.
`quarkus.oidc.tls.verification`	`none` - Disables TLS verification for the OIDC provider (for development).
`quarkus.oidc-proxy.enabled`	`true` - Enables the OIDC proxy feature, which simplifies OIDC integration.
`quarkus.http.auth.permission.*.paths`	Defines path patterns for different security policies (`permit`, `authenticated`).
`quarkus.http.auth.permission.*.policy`	Assigns a security policy to the corresponding path pattern.
`quarkus.keycloak.policy-enforcer.enabled`	`false` - Disables Keycloak Authorization Services policy enforcement. Set to `true` to enable policy enforcement so that MCP endpoints (e.g., `/mcp`, `/mcp/sse`) can be protected as Authorization Resources in Keycloak, linked to permissions and policies so that JWT access tokens are only issued to users who meet the associated policy.

Running Without Authentication

Set wanaku.http.auth=none (or export WANAKU_HTTP_AUTH=none) to run without Keycloak. No identity provider is required — all HTTP paths are opened via policy=permit automatically.

shell

# Via environment variable (recommended for containers / wanaku start local)
WANAKU_HTTP_AUTH=none java -jar quarkus-run.jar

# Via system property
java -Dwanaku.http.auth=none -jar quarkus-run.jar

IMPORTANT

wanaku.http.auth is a Wanaku-native property. Users do not need to know that Wanaku is built on Quarkus to configure authentication — the Quarkus implementation details stay hidden.

NOTE

How it works internally (AuthConfigSource): When wanaku.http.auth=none, a custom MicroProfile ConfigSource (ordinal 260) injects the following runtime overrides:

Property injected	Value	Reason
`quarkus.oidc.enabled`	`false`	Disables OIDC entirely at runtime
`quarkus.oidc.discovery-enabled`	`false`	Prevents eager Keycloak connection at startup
`quarkus.oidc.resource-metadata.enabled`	`false`	Disables resource metadata endpoint
`quarkus.oidc.mcp.enabled`	`false`	Disables the MCP OIDC tenant
`quarkus.oidc.mcp.discovery-enabled`	`false`	Same, for the MCP OIDC tenant used by OidcProxy
`quarkus.oidc.mcp.resource-metadata.enabled`	`false`	Disables resource metadata for MCP tenant
`quarkus.oidc.ns-{0..9}.enabled`	`false`	Disables per-namespace OIDC tenants
`quarkus.oidc.ns-{0..9}.discovery-enabled`	`false`	Same, for per-namespace OIDC tenants
`quarkus.oidc.ns-{0..9}.resource-metadata.enabled`	`false`	Disables resource metadata for namespace tenants
`quarkus.oidc-proxy.enabled`	`false`	Disables the OIDC proxy
`quarkus.http.auth.permission.authenticated.policy`	`permit`	Opens management / data-store APIs
`quarkus.http.auth.permission.mcp-authenticated.policy`	`permit`	Opens MCP namespace endpoints
`quarkus.http.auth.permission.web.policy`	`permit`	Opens the admin web UI

See the Usage Guide for end-to-end instructions.

Home Directory Resolution

Wanaku uses a single home directory for all persistent data. The location is resolved by WanakuHome in the following precedence order:

System property wanaku.home
Environment variable WANAKU_HOME
Default: ${user.home}/.wanaku

IMPORTANT

wanaku.home is a Wanaku-native property. It is resolved by the custom WanakuHome class, not directly by Quarkus MicroProfile Config. This ensures consistent resolution across all components (CLI, router, capabilities) regardless of Quarkus' own ${...} placeholder handling.

properties

# Set the Wanaku home directory (all components)
wanaku.home=/path/to/custom/home

shell

# Or via environment variable (recommended for containers / wanaku start local)
export WANAKU_HOME=/path/to/custom/home

shell

# Or via system property (direct router/capability start)
java -Dwanaku.home=/path/to/custom/home -jar quarkus-run.jar

What is stored under the home directory?

Directory	Purpose
`<home>/router/`	Infinispan data store (SoftIndexFileStore for tools, resources, namespaces)
`<home>/local/`	CLI-extracted service instances (when using `wanaku start local`)
`<home>/cache/`	CLI download cache for component ZIPs/JARs
`<home>/local/logs/`	Log files for router and capability services (`wanaku-router.log`, `<service>.log`)
`<home>/credentials`	CLI credential store (0600 permissions)

Behavior with `wanaku start local`

When using wanaku start local, the CLI automatically:

Sets WANAKU_HOME as an environment variable in all spawned child processes (router, capabilities, standalone services).
Passes -Dwanaku.home=<resolved-path> as a JVM argument to all Quarkus-based child processes (router, re-augmented capabilities).

This ensures all components write to the same resolved home directory without requiring manual configuration.

Behavior with direct JVM start

When starting the router or a capability directly with java -jar, the system property takes precedence over the environment variable. Set both to test precedence:

shell

export WANAKU_HOME=/tmp/env-var-home
java -Dwanaku.home=/tmp/sysprop-home -jar quarkus-run.jar
# Uses /tmp/sysprop-home (system property wins)

Health Check

These wanaku.router.health-check.* properties control the periodic health probing of registered capabilities.

Property	Description
`wanaku.router.health-check.enabled`	`true` - Enables periodic health checks of registered capability services.
`wanaku.router.health-check.interval-seconds`	`60` - The interval in seconds between health check sweeps.
`wanaku.router.health-check.max-concurrent`	`10` - The maximum number of concurrent health check probes.

gRPC Transport

Property	Description
`wanaku.bridge.grpc.transport.deadline-seconds`	`10` - The deadline in seconds for gRPC transport calls to capability services. Requests that exceed this deadline will be cancelled.
`wanaku.bridge.grpc.transport.tls.enabled`	`false` - Whether to enable TLS for gRPC transport calls to capability services.

Persistence (`core-persistence-infinispan`)

Property	Description
`wanaku.persistence.infinispan.base-folder`	Where to store Infinispan files (defaults to `${wanaku.home}/router/`).
`wanaku.infinispan.max-state-count`	`10` - The maximum number of historical states to keep for each service.

Namespaces

Property	Description
`wanaku.router.namespace-age-hard-limit`	`100000000000` - Threshold used to distinguish epoch-seconds from epoch-milliseconds when parsing namespace age timestamps. Values above this limit are interpreted as epoch-milliseconds; values at or below are interpreted as epoch-seconds.

2. Capabilities (Tool Services)

Common Capability Settings (`wanaku-capabilities-base`)

These settings apply to most tool services and are foundational for their operation.

Common Settings (All Modes)

These settings apply regardless of whether you use the shared HTTP listener or a separate gRPC server:

Property	Description
`wanaku.http.auth`	`keycloak` - Controls authentication mode for capability services. Set to `none` to disable OIDC client. Also settable via `WANAKU_HTTP_AUTH` environment variable.
`wanaku.service.name`	The unique, lowercase name of the service (e.g., `exec`, `http`).
`wanaku.service.base-uri`	The base URI scheme for tools provided by this service (e.g., `exec://`).
`wanaku.service.exec.allowed-executables`	Comma-separated absolute executable paths that the Exec tool may run.
`quarkus.qute.strict-rendering`	`false` - Allows for more lenient Qute template rendering.
`quarkus.oidc-client.auth-server-url`	The URL of the Keycloak realm for authentication.
`quarkus.oidc-client.client-id`	`wanaku-service` - The shared OIDC client ID for all capabilities.
`quarkus.oidc-client.credentials.secret`	The OIDC client secret for the capability. Must be replaced with a real secret.

Exec Tool Security

The wanaku.service.exec.allowed-executables property controls which programs the Exec tool can run. This is a critical security control because the Exec tool allows AI agents to invoke shell commands.

Security enforcement (ExecCommandPolicy):

Absolute paths required — The allowlist must use absolute paths like /usr/bin/python3, never relative names like python3. This prevents PATH hijacking attacks where a malicious binary shadows a legitimate one.
Shell metacharacters blocked — Characters that enable command injection (;, |, &, <, >, `, $) are rejected. This prevents chaining multiple commands or redirecting input/output.
Newlines blocked — Prevents header injection and multi-command injection via embedded newlines.
Empty allowlist = deny all — If allowed-executables is empty or unset, all execution requests are denied.
Path normalization — Both the allowlist and requested executable paths are resolved to absolute, normalized paths to prevent traversal tricks (e.g., /usr/bin/../../../tmp/malicious).

WARNING

Only allowlist the specific executables your deployment requires. Avoid broad allowlists like /usr/bin/* — explicitly name each trusted binary.

Secure configuration example:

properties

# Allow only specific, vetted executables
wanaku.service.exec.allowed-executables=/usr/bin/python3,/usr/local/bin/jq,/opt/myapp/scripts/data-export.sh

Insecure configuration (do not use):

properties

# DANGEROUS: Uses relative paths and broad allowlist
wanaku.service.exec.allowed-executables=python3,bash,sh

Shared HTTP Listener (Recommended)

By default, capabilities are configured to share the HTTP listener with gRPC, avoiding the need for a separate gRPC server port. This simplifies deployment and configuration.

Property	Description
`quarkus.http.host-enabled`	`true` - Enables the HTTP server for capabilities (required when using shared listener).
`quarkus.http.port`	The HTTP port for the capability (e.g., `9000` for `http` service).
`quarkus.http.host`	`0.0.0.0` - Binds the HTTP server to all available network interfaces.
`quarkus.grpc.server.use-separate-server`	`false` - The gRPC server shares the HTTP listener (recommended for simpler deployment).

Note: When use-separate-server=false, the quarkus.grpc.server.port property is ignored because gRPC uses the HTTP port.

Separate gRPC Server (Optional)

If you prefer to use a separate gRPC server, set quarkus.grpc.server.use-separate-server=true and configure the gRPC-specific properties:

Property	Description
`quarkus.http.host-enabled`	`false` - Disables the standard HTTP server (not needed with separate gRPC).
`quarkus.grpc.server.use-separate-server`	`true` - Uses a separate gRPC server with its own port.
`quarkus.grpc.server.host`	`0.0.0.0` - Binds the gRPC server to all available network interfaces.
`quarkus.grpc.server.port`	A unique port for each capability's gRPC server (e.g., `9009` for `exec`).

Common Service Registration Settings

These wanaku.service.registration.* properties are available for all capabilities to manage their discovery and lifecycle.

Property	Description
`wanaku.service.registration.enabled`	`true` - Enables the service registration feature. Found in archetypes.
`wanaku.service.registration.uri`	The URI of the router backend for registration (e.g., `http://localhost:8080`).
`wanaku.service.registration.interval`	`10s` - The interval at which the service should ping the router to show it's alive.
`wanaku.service.registration.retries`	`3` - Number of times to retry a failed registration.
`wanaku.service.registration.retry-wait-seconds`	`1` - Seconds to wait before retrying a failed registration.
`wanaku.service.registration.delay-seconds`	`3` - Seconds to delay the initial registration after startup.
`wanaku.service.registration.announce-address`	A custom address to announce to the router, overriding the auto-detected one.

Secret Encryption

Secrets can be encrypted at rest using AES-256. Set both environment variables to enable:

Environment Variable	Description
`WANAKU_SECRETS_ENCRYPTION_PASSWORD`	Password for key derivation
`WANAKU_SECRETS_ENCRYPTION_SALT`	Salt for key derivation

When both are set, secrets are automatically encrypted when written and decrypted when read.

3. CLI

Configuration for the Wanaku command-line interface (wanaku-cli).

Property	Description
`wanaku.cli.tool.create-cmd`	The full Maven command to execute when creating a new tool service via `wanaku tool create`.
`wanaku.cli.resource.create-cmd`	The full Maven command to execute when creating a new resource provider via `wanaku resource create`.
`wanaku.cli.mcp.create-cmd`	The full Maven command to execute when creating a new MCP server via `wanaku mcp create`.
`wanaku.cli.components.*`	URL templates for downloading various Wanaku components. `%s` is replaced with the version number.
`wanaku.cli.default-services`	A comma-separated list of default services to start automatically when running the router.

4. Archetypes

These properties are found in the project archetypes and serve as templates for new services.

`wanaku-mcp-servers-archetype`

Property	Description
`wanaku.mcp.service.name`	The name of the new MCP service, typically derived from the `name` variable.
`wanaku.mcp.service.namespace`	The namespace the MCP service will operate on.
`wanaku.service.registration.mcp-forward-address`	The address to forward MCP messages to.

`wanaku-provider-archetype` & `wanaku-tool-service-archetype`

Property	Description
`wanaku.service.service.configurations.*`	A way to define user-exposable configurations for a service. The key becomes the configuration name.
`wanaku.service.service.defaults.*`	Defines default values for the corresponding `configurations`.

5. Testing

Properties primarily used when running tests.

Property	Description
`keycloak.docker.image`	Overrides the default Keycloak Docker image used for tests. This is set via a system property in the `pom.xml`, not in `application.properties`.
`%test.quarkus.log.file.enable`	`true` - Enables logging to a file during tests.
`%test.quarkus.log.file.path`	`target/wanaku.log` - The path to the log file for test runs.

Global Concepts

Quarkus Profiles

Quarkus uses profiles to manage environment-specific configurations. You will see properties prefixed with %dev, %test, or other custom profiles. These properties are only active when that profile is enabled.

%dev: Used when running in development mode (quarkus dev).
%test: Used when running automated tests.
%prod: Used for production deployments (default when no profile is specified).

Environment Variables

Most properties can be set via environment variables by converting the property name:

Convert to uppercase
Replace dots (.) with underscores (_)
Replace hyphens (-) with underscores (_)

Example:

properties

quarkus.http.port=8080

Becomes:

shell

QUARKUS_HTTP_PORT=8080

Configuration Examples

Example: Router Backend Without Authentication (No Keycloak)

The quickest way to run Wanaku locally without setting up an identity provider:

shell

# Environment variable — no changes to any properties file needed
export WANAKU_HTTP_AUTH=none
java -jar quarkus-run.jar

Or equivalently via a config/application.properties override file:

properties

wanaku.http.auth=none

This automatically opens all protected endpoints (/api/v1/management/*, /mcp/*, /admin/*, etc.) without requiring a token, while OIDC infrastructure stays initialized (preventing startup errors from the embedded OIDC proxy extension).

Example: Router Backend with Custom OIDC

properties

# application.properties for router backend
quarkus.http.port=8080
quarkus.http.cors.enabled=true
quarkus.http.cors.origins=http://localhost:3000,https://my-frontend.example.com

auth.server=https://keycloak.example.com
auth.proxy=https://wanaku.example.com

quarkus.oidc.client-id=wanaku-mcp-router
quarkus.oidc.application-type=hybrid
quarkus.oidc.tls.verification=required

wanaku.persistence.infinispan.base-folder=/var/lib/wanaku/data
wanaku.infinispan.max-state-count=20

Example: Tool Service with Shared HTTP Listener (Recommended)

properties

# application.properties for a tool service using shared HTTP listener
quarkus.http.host-enabled=true
quarkus.http.port=9010
quarkus.http.host=0.0.0.0

# gRPC shares the HTTP listener - no separate port needed
quarkus.grpc.server.use-separate-server=false

wanaku.service.name=my-custom-tool
wanaku.service.base-uri=custom://

wanaku.service.registration.enabled=true
wanaku.service.registration.uri=http://wanaku-router:8080
wanaku.service.registration.interval=15s
wanaku.service.registration.announce-address=my-custom-tool.example.com:9010

quarkus.oidc-client.auth-server-url=https://keycloak.example.com/realms/wanaku
quarkus.oidc-client.client-id=wanaku-service
quarkus.oidc-client.credentials.secret=${WANAKU_SERVICE_SECRET}

The realm name defaults to wanaku and can be configured via the AUTH_REALM environment variable or the auth.realm property.

Example: Tool Service with Separate gRPC Server

properties

# application.properties for a tool service using separate gRPC server
quarkus.http.host-enabled=false

quarkus.grpc.server.use-separate-server=true
quarkus.grpc.server.host=0.0.0.0
quarkus.grpc.server.port=9010

wanaku.service.name=my-custom-tool
wanaku.service.base-uri=custom://

wanaku.service.registration.enabled=true
wanaku.service.registration.uri=http://wanaku-router:8080
wanaku.service.registration.interval=15s
wanaku.service.registration.announce-address=my-custom-tool.example.com:9010

quarkus.oidc-client.auth-server-url=https://keycloak.example.com/realms/wanaku
quarkus.oidc-client.client-id=wanaku-service
quarkus.oidc-client.credentials.secret=${WANAKU_SERVICE_SECRET}

Example: CLI Configuration

properties

# ~/.wanaku/cli.properties
wanaku.cli.default-services=http,exec,tavily

Example: Enabling Secret Encryption

shell

export WANAKU_SECRETS_ENCRYPTION_PASSWORD="your-strong-password"
export WANAKU_SECRETS_ENCRYPTION_SALT="unique-salt-value"

Additional Resources

Quarkus Configuration Guide - Comprehensive Quarkus configuration documentation
Keycloak Documentation - OIDC and authentication setup
Infinispan Configuration - Persistence layer configuration

Wanaku Configuration ​

Configuration Basics ​

What is application.properties? ​

Where is application.properties located? ​

How to override configuration at runtime ​

1. External application.properties file ​

2. System properties (-D flags) ​

3. Environment variables ​

Priority order ​

1. Router Backend ​

General & HTTP ​

Multi-Component Protocol (MCP) Server ​

Authentication & Authorization (OIDC) ​

Running Without Authentication ​

Home Directory Resolution ​

What is stored under the home directory? ​

Behavior with wanaku start local ​

Behavior with direct JVM start ​

Health Check ​

gRPC Transport ​

Persistence (core-persistence-infinispan) ​

Namespaces ​

2. Capabilities (Tool Services) ​

Common Capability Settings (wanaku-capabilities-base) ​

Common Settings (All Modes) ​

Exec Tool Security ​

Shared HTTP Listener (Recommended) ​

Separate gRPC Server (Optional) ​

Common Service Registration Settings ​

Secret Encryption ​

3. CLI ​

4. Archetypes ​

wanaku-mcp-servers-archetype ​

wanaku-provider-archetype & wanaku-tool-service-archetype ​

5. Testing ​

Global Concepts ​

Quarkus Profiles ​

Environment Variables ​

Configuration Examples ​

Example: Router Backend Without Authentication (No Keycloak) ​

Example: Router Backend with Custom OIDC ​

Example: Tool Service with Shared HTTP Listener (Recommended) ​

Example: Tool Service with Separate gRPC Server ​

Example: CLI Configuration ​

Example: Enabling Secret Encryption ​

Additional Resources ​

Wanaku Configuration

Configuration Basics

What is `application.properties`?

Where is `application.properties` located?

How to override configuration at runtime

1. External `application.properties` file

2. System properties (`-D` flags)

3. Environment variables

Priority order

1. Router Backend

General & HTTP

Multi-Component Protocol (MCP) Server

Authentication & Authorization (OIDC)

Running Without Authentication

Home Directory Resolution

What is stored under the home directory?

Behavior with `wanaku start local`

Behavior with direct JVM start

Health Check

gRPC Transport

Persistence (`core-persistence-infinispan`)

Namespaces

2. Capabilities (Tool Services)

Common Capability Settings (`wanaku-capabilities-base`)

Common Settings (All Modes)

Exec Tool Security

Shared HTTP Listener (Recommended)

Separate gRPC Server (Optional)

Common Service Registration Settings

Secret Encryption

3. CLI

4. Archetypes

`wanaku-mcp-servers-archetype`

`wanaku-provider-archetype` & `wanaku-tool-service-archetype`

5. Testing

Global Concepts

Quarkus Profiles

Environment Variables

Configuration Examples

Example: Router Backend Without Authentication (No Keycloak)

Example: Router Backend with Custom OIDC

Example: Tool Service with Shared HTTP Listener (Recommended)

Example: Tool Service with Separate gRPC Server

Example: CLI Configuration

Example: Enabling Secret Encryption

Additional Resources