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:

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-barn-backend/src/main/resources/application.properties
• Tool Services: each downstream MCP server has its own src/main/resources/application.properties (see the Wanaku Capabilities Java SDK)
• 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:

my-deployment/
├── wanaku-barn-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:

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

3. Environment variables

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

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

Priority order

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

1. System properties (-D)
2. Environment variables
3. External config/application.properties
4. 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-barn-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.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.

# 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:

1. System property wanaku.home
2. Environment variable WANAKU_HOME
3. 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, MCP servers) regardless of Quarkus' own ${...} placeholder handling.

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

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

# Or via system property (direct router/MCP server 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 MCP servers (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, MCP servers, standalone services).
• Passes -Dwanaku.home=<resolved-path> as a JVM argument to all Quarkus-based child processes (router, re-augmented MCP servers).

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 an MCP server directly with java -jar, the system property takes precedence over the environment variable. Set both to test precedence:

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 downstream MCP servers.

Property	Description
wanaku.router.health-check.enabled	true - Enables periodic health checks of registered downstream MCP servers.
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.

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. Downstream MCP Servers

Common Settings

These settings apply to downstream MCP servers and are foundational for their operation.

Common Settings (All Modes)

These settings apply to all downstream MCP servers:

Property	Description
wanaku.http.auth	keycloak - Controls authentication mode for downstream MCP servers. 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 downstream MCP servers.
quarkus.oidc-client.credentials.secret	The OIDC client secret for the MCP server. 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):

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

2. Shell metacharacters blocked — Characters that enable command injection (;, |, &, <, >, `, $) are rejected. This prevents chaining multiple commands or redirecting input/output.

3. Newlines blocked — Prevents header injection and multi-command injection via embedded newlines.

4. Empty allowlist = deny all — If allowed-executables is empty or unset, all execution requests are denied.

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

# 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):

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

HTTP Listener

Property	Description
quarkus.http.host-enabled	true - Enables the HTTP server for downstream MCP servers.
quarkus.http.port	The HTTP port for the MCP server (e.g., 9000 for http service).
quarkus.http.host	0.0.0.0 - Binds the HTTP server to all available network interfaces.

Common Service Registration Settings

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

Property	Description
wanaku.service.registration.enabled	true - Enables the service registration feature.
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. 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:

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

Example:

quarkus.http.port=8080

Becomes:

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:

# 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:

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

# 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

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

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: CLI Configuration

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

Example: Enabling Secret Encryption

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