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

Configuration for the Barn backend (wanaku-barn-backend), which provides the management and persistence APIs. The backend does not serve MCP.

General & HTTP

Property	Description
quarkus.http.port	8180 - The HTTP port of the Barn 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.

Authentication & Authorization

The Barn backend does not perform authentication or authorization itself. These concerns are handled by the Wanaku Governed Execution Proxy (GEP), which sits in front of the backend and uses the oauth2 proxy. No auth-related properties (such as wanaku.http.auth) are required to run the backend.

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)
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>/barn/	Infinispan data store (SoftIndexFileStore) for data stores, service catalogs and templates, catalog versions, audit events. See Backup, Restore and Upgrade.
<home>/local/logs/	Router log file (wanaku-router.log) when running with the local Quarkus profile
<home>/credentials	CLI credential store (0600 permissions)

NOTE

Older versions stored the Infinispan data under <home>/router/. If you have existing data there, move it to the new location before starting Wanaku Barn (e.g., mv ~/.wanaku/router ~/.wanaku/barn), or keep using the old location by setting wanaku.persistence.infinispan.base-folder=${wanaku.home}/router/. Docker Compose and operator deployments keep their existing volumes, so no manual migration is needed there.

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)

Persistence (Infinispan)

Property	Description
wanaku.persistence.infinispan.base-folder	Where to store Infinispan files (defaults to ${wanaku.home}/barn/).
wanaku.infinispan.max-state-count	10 - The maximum number of historical states to keep for each service.
wanaku.persistence.infinispan.max-entries	10000 - The maximum number of entries that each cache keeps in memory. With the file store, the other entries stay on disk.
wanaku.persistence.infinispan.file-store	true - Stores the caches on disk (SoftIndexFileStore). Set to false to keep the data in memory only.

Service Catalog Versions

Property	Description
wanaku.catalog.max-versions	50 - The number of versions to keep for each service catalog and template. Barn never removes the active version.
wanaku.catalog.purge-after	Not set - The time (ISO 8601 duration, for example P30D) after which Barn deletes removed catalogs and templates permanently. Purge is disabled when this property is not set.
wanaku.catalog.purge-interval	1h - How often Barn checks for removed catalogs and templates to purge.

Audit Trail

Property	Description
wanaku.audit.max-records	10000 - The number of audit events to keep. See Barn Audit Trail.
wanaku.audit.stream-id	barn - The stream_id value of the audit events.

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.

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.

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

# 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

wanaku.persistence.infinispan.base-folder=/var/lib/wanaku/data

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