Install and configure the AI proxy
The AI proxy runs separately from the PPM application. It routes Aviator requests to configured AI providers.
Prepare the proxy host
Prepare a host for the proxy and an Oracle schema that the proxy can reach.
-
Obtain and extract the proxy package from the OpenText Marketplace.
-
Install Python 3.13. Python 3.12 is also reported to work.
-
Prepare Oracle schema credentials. The host must be able to connect to the database.
Install the proxy
Run the installer from the extracted package directory.
To install the proxy:
Linux or Git Bash
Run:
cd /path/to/llm-gateway-package sh install.sh
Windows without Git Bash
The package does not include an installation batch file. Run the Python installer:
cd C:\path\to\llm-gateway-package python installer\apply_install.py --media .
Configure the database
During installation, choose the schema option that matches the database setup.
To configure the database:
-
Choose option 1 to create a schema when system or DBA credentials are available.
-
Choose option 2 when a DBA has already created the schema.
-
Choose option 3 only when installing a second proxy node.
Enter the JDBC URL in this format: jdbc:oracle:thin:@dbhost:1521/ORCLPDB1. At the port prompt, press Enter to use port 8000. Do not store passwords in .env.
Start and verify the proxy
Set the bootstrap option before starting the proxy. The Connect operation uses it to create the initial secret without an administrator key.
Add this line to .env:
BOOTSTRAP_SECRET_ENDPOINT_OPEN=true
Keep AGENTS_ENABLED off. This mode does not support the bootstrap setting.
To start and verify the proxy:
Start the proxy with the script for the operating system:
sh start.sh
On Windows, run start.bat. The installer creates this file.
From the application host, check both health endpoints. Each returns HTTP 200 when the service is ready:
curl http://<proxy-host>:8000/health curl http://<proxy-host>:8000/health/readiness
Stop the proxy with sh stop.sh on Linux or stop.bat on Windows. Store the secrets/ directory securely off the host. Stored keys cannot be read if this directory is lost.
Connect to the proxy
Enable the required feature toggles, connect to the proxy URL, and select a configured model and virtual key.
To connect the proxy:
-
In Administration > New Features > Feature Toggles, enable the Aviator feature (
ENABLE_AI) and the AI Proxy feature (ENABLE_AI_PROXY). -
Open Administration > System Admin > AI Proxy Configuration. Enter
http://<proxy-host>:8000as the proxy URL. Do not add a trailing slash or/v1. -
Select Connect. The page reloads to allow the embedded proxy interface. Wait until the connection status shows Connected.
-
Add a model and create a virtual key in the proxy configuration. Provider API keys remain on the proxy.
-
In the assistant configuration, select the virtual key and model, then select Apply.
Chat through the proxy does not require MCP. Skills and tools do. To enable them, set com.kintana.core.server.MCP_SERVER_URL in server.conf and restart the application server. For MCP setup details, see Set up an MCP Server.
Send a chat prompt to verify the connection. Users do not sign in to the proxy.
Troubleshoot connection issues
Check the following items when the proxy does not connect or respond as expected.
-
Connection timeout: From the application host, check
/health. Verify the proxy host, protocol, and firewall access. -
Master key required: Confirm that
BOOTSTRAP_SECRET_ENDPOINT_OPEN=trueis in.env. Restart the proxy and select Connect again. -
Blank embedded page: Wait for the page reload. If it remains blank, set
UI_FRAME_ANCESTORSto the exact application origin, such ashttp://ppm-host:8080. Do not set it to'self'alone. -
No virtual key or model: Connect succeeded, but the virtual key and model are not applied in Aviator configuration.
-
Proxy menu is missing: Enable the Enable AI Proxy (LLM Gateway) toggle and verify the administrator has the required access grant.
-
Readiness check returns HTTP 503: Check Oracle connectivity and the JDBC credentials.
Add a standby node
A second node is optional. A standard installation uses one node. The optional second node acts as a standby and uses the same Oracle schema; a load balancer is not required.
To add a standby node:
-
On the first node, run
sh cluster.sh enable. On Windows, runcluster.bat enable. Confirm the node URL and set a passphrase with at least 12 characters. Restart the first node if its URL changes. -
Install the same package on the second node. Choose installer option 3. Use the same JDBC URL and application user, enter the second node URL, and use the same passphrase. Start the second node.
-
Connect from Aviator to either node URL. Check cluster status with
sh cluster.sh status.

