Introduction
We’re living through one of the most volatile stretches the AI world has seen. New models drop constantly, and every hyperscaler seems to be racing to ship its own flavor of “AI tooling” before the ink dries on the last announcement. It’s a lot to keep up with.
Out of everything I’ve tried this year, the one that’s actually stuck in my daily workflow is Oracle’s Private Agent Factory (OPAF).
The early releases had their share of bugs, nothing unusual for a first-generation product. The latest OPAF release has ironed out most of those issues. One of the bigger pain points before was that there was no registered Linux service for OPAF, so every time you rebooted the box, you had to manually restart the service yourself. That’s been fixed now.
The headline feature of this release is the new Deep Data Research Agent, purpose-built for complex research and analysis. Oracle also added agent observability, so you can trace exactly what’s happening across LLM calls, tool invocations, agent turns, and workflow steps – something that was sorely missing before. On top of that, there’s broader data connectivity, with S3-compatible object storage now available as a native source, complete with include/exclude filters for proper governance, plus improvements to agentic research and workflow orchestration. This is clearly a platform maturing fast.
So what is OPAF, exactly?
If you haven’t come across it yet: Private Agent Factory is Oracle’s no-code/low-code playground for building AI agents that work safely with your company’s own data.
Instead of writing custom glue code to wire models to databases, you build visually, dragging components together into workflows that are functional and context-aware. Business users and engineers can both work in the same canvas, which is rare for a tool this capable.
A couple of things stand out to me:
-
It’s genuinely no-code first. You’re not fighting the tool to avoid writing Python just to connect a model to a table.
-
It’s data-aware by design. Because it sits close to Oracle AI Database, agents get memory, vector search, and governed data access baked in rather than bolted on.
Installation
In this blog, I will illustrate how to install the latest OPAF version 26.4 in an OCI VM instance.
For this walkthrough, I’ll install OPAF on an Oracle Linux 8 (OEL8) virtual machine in OCI, following Oracle’s official prerequisites documentation: Oracle OPAF Installation Prerequisites.
I’m going with Oracle Linux 8 because it’s currently the only supported Linux release for this setup. Here’s the full list of supported operating systems at the moment:
You need to download the software using OPAF Download, as it requires separate directories for installation and staging the OPAF binary.
|
/OPAF_DATA/OPAF_CONFIG - Installation
/OPAF_DATA/OPAF_INSTALLATION - OPAF installation binary
|
Issues I hit during installation
Now for the part nobody writes about. Here are the problems I ran into.
Missing Podman package
My first install failed outright. OPAF is built on containers, so Podman isn’t optional, but the installer doesn’t check for it up front. It gets several steps in, then dies:
|
================================================================
Oracle Private AI Agent agent_factory Interactive Installer ��
================================================================
[INFO] This script will guide you through the setup process.
[INFO] Completed steps will be skipped on reruns.
[WARNING] Please run this script as a non-root user.
Are you on a corporate network that requires an HTTP/HTTPS proxy? (y/N): n
[INFO] Proxy disabled.
[INFO] Detected OS: Linux
Enter 1 if you are on a Standard Oracle Linux machine or 2 if you are on OCI [1]:
[INFO] Starting setup for Standard Oracle Linux...
Enter your Linux username [opc]:
[INFO] Starting step: Configure Podman storage
[INFO] Configuring Podman storage at '/scratch/podman_storage'...
[SUCCESS] Step 'Configure Podman storage' completed.
[INFO] Starting step: Configure subuid/subgid
[INFO] Configuring subuid and subgid for user 'opc'...
[INFO] subuids already configured for opc.
[INFO] subgids already configured for opc.
[INFO] Running 'podman system migrate'...
./interactive_install.sh: line 289: podman: command not found
[opc@opaf-01 OPAF_DATA]$ sudo dnf install podman
Last metadata expiration check: 0:45:10 ago on Wed 15 Jul 2026 07:09:41 PM GMT.
|
Notice that it happily configures Podman storage and subuid/subgid first, then falls over when it actually tries to call the binary.
Fix: Install Podman before you run the installer.
Restarting the installation
If you want to start clean, you can reset the installer state. Worth doing just to be safe:
|
[opc@opaf-01 OPAF_DATA]$ ./interactive_install.sh --reset
[WARNING] Resetting installer state. All steps will be re-run.
[SUCCESS] State directory cleared.
[opc@opaf-01 OPAF_DATA]$
|
The newer version also introduces a few extra interactive prompts. One I mentioned earlier is the step that registers a service so the containers come back cleanly after a reboot:
|
[INFO] Starting step: Set Linux service to safely start and stop the container
Create Linux user service for start/stop on VM reboot? (y/N): y
Removed /home/opc/.config/systemd/user/default.target.wants/agentfactory_startstop.service.
Created symlink /home/opc/.config/systemd/user/default.target.wants/agentfactory_startstop.service → /home/opc/.config/systemd/user/agentfactory_startstop.service.
[INFO] Start/stop service set up correctly.
|
Here’s the full run after the reset:
|
================================================================
Oracle Private AI Agent agent_factory Interactive Installer ��
================================================================
[INFO] This script will guide you through the setup process.
[INFO] Completed steps will be skipped on reruns.
[WARNING] Please run this script as a non-root user.
Are you on a corporate network that requires an HTTP/HTTPS proxy? (y/N): n
[INFO] Proxy disabled.
[INFO] Detected OS: Linux
Enter 1 if you are on a Standard Oracle Linux machine or 2 if you are on OCI [1]: 2
[INFO] Starting setup for OCI Oracle Linux VM...
Enter your Linux username [opc]:
[INFO] Detected Podman: podman version 4.9.4-rhel
[INFO] Current Podman graphroot: /scratch/podman_storage/storage/graphroot
Are you already using rootless Podman on this user and want to keep existing config/containers untouched? (Y/n): n
[SUCCESS] Step 'Install Podman and configure SELinux' already completed. Skipping.
[INFO] Starting step: Configure Podman storage
Enter a mount point with at least 60GB of space (e.g., /scratch): /OPAF_DATA/OPAF_CONFIG
[INFO] Setting up Podman storage at '/OPAF_DATA/OPAF_CONFIG'...
[SUCCESS] Step 'Configure Podman storage' completed.
[INFO] Starting step: Log in to container registry
[INFO] Please log in to Oracle Container Registry.
[INFO] You can get a token from https://container-registry.oracle.com/
Authenticating with existing credentials for container-registry.oracle.com
Existing credentials are valid. Already logged in to container-registry.oracle.com
[SUCCESS] Step 'Log in to container registry' completed.
[INFO] Starting step: Install podman-compose
[SUCCESS] Step 'Install podman-compose' completed.
[INFO] Starting step: Enable user linger
[INFO] Linger mode is already enabled for user 'opc'.
[SUCCESS] Step 'Enable user linger' completed.
[INFO] Starting step: Configure firewall
[INFO] Configuring firewall to open port 8080...
success
success
[SUCCESS] Step 'Configure firewall' completed.
[INFO] Starting step: Perform manual DB setup
[INFO] The following steps are for connecting to your own existing Oracle 23ai Database.
*******************************************************************************************************
* *
* NOTE: If you choose the 'Quickstart' mode later during the 'make build' and 'make install' step, *
* a local 23ai Database will be automatically created and configured for you. *
* In that case, you can skip the manual steps below. *
* *
*******************************************************************************************************
Do you want to proceed with the manual database setup? (y/N): n
[INFO] Skipping manual database setup.
[SUCCESS] Step 'Perform manual DB setup' completed.
[INFO] Starting step: Set Linux service to safely start and stop the container
Create Linux user service for start/stop on VM reboot? (y/N): y
Removed /home/opc/.config/systemd/user/default.target.wants/agentfactory_startstop.service.
Created symlink /home/opc/.config/systemd/user/default.target.wants/agentfactory_startstop.service → /home/opc/.config/systemd/user/agentfactory_startstop.service.
[INFO] Start/stop service set up correctly.
[SUCCESS] Step 'Set Linux service to safely start and stop the container' completed.
[INFO] Starting step: Build container images
[INFO] Building container images with 'make build'. This will take several minutes.
Press [Enter] to run 'make build'...
bash build-image.sh
Successfully connected to container-registry.oracle.com
1) prod
2) quickstart
Enter choice (1 or 2): 2
Building the images necessary in Quickstart mode
You selected Quickstart mode. Confirm? (yes/no) [yes]: yes
Trying to pull container-registry.oracle.com/os/oraclelinux:8...
Getting image source signatures
Copying blob fa8041109490 done |
Copying config 45270dc6cf done |
Writing manifest to image destination
45270dc6cf2314153c6e4bf23c3bf6c39350a286ed95899546ea841f1070b804
STEP 1/20: FROM container-registry.oracle.com/os/oraclelinux:8
STEP 2/20: ARG http_proxy
--> 614a7074efb1
STEP 3/20: ARG https_proxy
--> ac631e272a4a
STEP 4/20: ARG HTTP_PROXY
--> de465f61ffdd
STEP 5/20: ARG HTTPS_PROXY
--> a6d9ec7a7218
STEP 6/20: ARG ARCH=x86_64
--> c3ce3cdd1b7c
STEP 7/20: ARG JDK_ARCH=x64
--> 0890dbd7c11a
STEP 8/20: ENV ARCH=${ARCH}
--> cbe98b4cab99
STEP 9/20: ENV JDK_ARCH=${JDK_ARCH}
--> c5a03b1b2386
STEP 10/20: RUN yum install -y https://download.oracle.com/java/23/archive/jdk-23_linux-${JDK_ARCH}_bin.rpm https://download.oracle.com/otn_software/linux/instantclient/2370000/oracle-instantclient-basic-23.7.0.25.01-1.el8.${ARCH}.rpm https://download.oracle.com/otn_software/linux/instantclient/2370000/oracle-instantclient-sqlplus-23.7.0.25.01-1.el8.${ARCH}.rpm https://download.oracle.com/otn_software/linux/instantclient/2370000/oracle-instantclient-tools-23.7.0.25.01-1.el8.${ARCH}.rpm bash vim wget cronie hostname unzip libgfortran libgomp openblas numactl libomp gtk3 alsa-lib libX11-xcb libatomic file zip gcc && yum clean all && rm -rf /var/cache/yum
Oracle Linux 8 BaseOS Latest (x86_64) 121 MB/s | 151 MB 00:01
Oracle Linux 8 Application Stream (x86_64) 108 MB/s | 83 MB 00:00
Last metadata expiration check: 0:00:13 ago on Mon Jul 20 13:48:00 2026.
jdk-23_linux-x64_bin.rpm 5.0 MB/s | 231 MB 00:45
oracle-instantclient-basic-23.7.0.25.01-1.el8.x 45 MB/s | 79 MB 00:01
oracle-instantclient-sqlplus-23.7.0.25.01-1.el8 4.8 MB/s | 4.6 MB 00:00
oracle-instantclient-tools-23.7.0.25.01-1.el8.x 1.6 MB/s | 1.1 MB 00:00
Package bash-4.4.20-6.el8_10.x86_64 is already installed.
Dependencies resolved.
-- removed installation and container downloading steps.
+------------------+---------+--------+--------------------------------+----------------------+------------------------------------------------------+
| Image | Status | Size | Created | Image ID | Tags |
+------------------+---------+--------+--------------------------------+----------------------+------------------------------------------------------+
| applied-ai-label | SUCCESS | 6.3 GB | 2026-07-20T13:56:17.424379193Z | 579fb313fc390696e1d6 | localhost/applied-ai-label:26.4.0.0.0 |
+------------------+---------+--------+--------------------------------+----------------------+------------------------------------------------------+
| db23aifree | SUCCESS | 8.9 GB | 2025-02-04T11:02:11.766185356Z | ac5f0e5fb44326e93580 | container-registry.oracle.com/database/free:23.7.0.0 |
+------------------+---------+--------+--------------------------------+----------------------+------------------------------------------------------+
[SUCCESS] Step 'Build container images' completed.
[INFO] Starting step: Launch application containers
[INFO] Bringing containers up with 'make install'.
[WARNING] You will be prompted to choose an installation mode.
[INFO] If you choose quickstart for a fresh install, deploy.sh will prompt for the local database admin password
bash deploy.sh; \
|
Troubleshooting: make install Fails on Container Startup Timeout
During installation, make install failed with the following error, even after all three required container images have been confirmed present:
|
Select installation mode:
1) prod
2) quickstart
Selection: 2
You have chosen Quickstart mode. Confirm? (yes/no):
yes
Deploying Oracle AI Database Private Agent Factory in Quickstart mode...
Quickstart fresh install needs a database admin password for one-time local DB bootstrap.
Enter quickstart database admin password:
Re-enter quickstart database admin password:
Select Agent Factory web UI access:
1) Private to this host: the web UI is reachable only from this machine.
2) Reachable from other hosts: the web UI listens on all host interfaces, subject to network and firewall rules.
Selection: 2
You have chosen Reachable from other hosts. Confirm? (yes/no):
yes
Configured Agent Factory web UI access as Reachable from other hosts.
Confirming container 'oracle-applied-ai-label' is in a running state...
- Waiting for container to be ready...
- Waiting for container to be ready...
- Waiting for container to be ready...
- Waiting for container to be ready...
- Waiting for container to be ready...
- Waiting for container to be ready...
- Waiting for container to be ready...
- Waiting for container to be ready...
- Waiting for container to be ready...
- Waiting for container to be ready...
- Waiting for container to be ready...
- Waiting for container to be ready...
- Waiting for container to be ready...
Error: Timeout: Container 'oracle-applied-ai-label' did not enter a running state within 60 seconds.
Logs can be found at: ./deploy.log
make: *** [Makefile:62: install] Error 1
[ERROR] 'make install' failed. Check logs.
[opc@opaf-01 OPAF_INSTALLATION]$
|
At first glance, this looks like a container health or resource issue. Before making any changes, it’s worth confirming the image and container state:
|
podman images - check the pull images from oracle repository
podman ps -a - check the container status
|
Output of the image status:
|
[opc@opaf-01 OPAF_INSTALLATION]$ podman images
REPOSITORY TAG IMAGE ID CREATED SIZE
localhost/applied-ai-label 26.4.0.0.0 c1a748ed5a14 47 hours ago 6.79 GB
container-registry.oracle.com/os/oraclelinux 8 45270dc6cf23 6 days ago 259 MB
container-registry.oracle.com/database/free 23.7.0.0 ac5f0e5fb443 17 months ago 9.55 GB
[opc@opaf-01 OPAF_INSTALLATION]$
|
You should see three images pulled from the Oracle Container Registry. If all three are present and correctly tagged, the images aren’t the problem; something in the deployment orchestration is.
Running make install directly surfaces the actual cause:
|
Traceback (most recent call last):
File "/home/opc/.local/bin/podman-compose", line 7, in <module>
from podman_compose import main
ModuleNotFoundError: No module named 'podman_compose'
[2026-07-21 19:18:59] [deploy.sh] - Waiting for container to be ready...
[2026-07-21 19:19:04] [deploy.sh] - Waiting for container to be ready...
[2026-07-21 19:19:09] [deploy.sh] - Waiting for container to be ready...
[2026-07-21 19:19:14] [deploy.sh] - Waiting for container to be ready...
|
Root cause: the podman-compose binary exists on the system, but its underlying Python module is missing. deploy.sh calls podman-compose to bring up the containers, and without the module, that call fails silently from the wrapper script’s perspective. It appears as a container that never reaches a running state, which is why the timeout message is misleading rather than diagnostic.
Fix: Install a current Python version and reinstall podman-compose through it:
|
sudo dnf install -y python3.11
which -a python3.8 python3.9 python3.11 python3.12 2>/dev/null
python3.11 -m ensurepip --upgrade --user
python3.11 -m pip install --user --upgrade pip
python3.11 -m pip install --user podman-compose
|
Sample output of the pip upgrade and installation logs.
|
[opc@opaf-01 OPAF_INSTALLATION]$ python3.11 -m ensurepip --upgrade --user
Looking in links: /tmp/tmp05tig86j
Processing /tmp/tmp05tig86j/setuptools-65.5.1-py3-none-any.whl
Processing /tmp/tmp05tig86j/pip-22.3.1-py3-none-any.whl
Installing collected packages: setuptools, pip
Successfully installed pip-22.3.1 setuptools-65.5.1
[opc@opaf-01 OPAF_INSTALLATION]$
|
Validate the install:
|
[opc@opaf-01 OPAF_INSTALLATION]$ python3.11 -m pip install --user podman-compose
Collecting podman-compose
Downloading podman_compose-1.6.0-py3-none-any.whl.metadata (5.6 kB)
Collecting python-dotenv (from podman-compose)
Downloading python_dotenv-1.2.2-py3-none-any.whl.metadata (27 kB)
Collecting pyyaml (from podman-compose)
Downloading pyyaml-6.0.3-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.metadata (2.4 kB)
Downloading podman_compose-1.6.0-py3-none-any.whl (53 kB)
Downloading python_dotenv-1.2.2-py3-none-any.whl (22 kB)
Downloading pyyaml-6.0.3-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (806 kB)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 806.6/806.6 kB 68.1 MB/s 0:00:00
Installing collected packages: pyyaml, python-dotenv, podman-compose
Successfully installed podman-compose-1.6.0 python-dotenv-1.2.2 pyyaml-6.0.3
[opc@opaf-01 OPAF_INSTALLATION]$
|
Expected output:
|
[opc@opaf-01 OPAF_INSTALLATION]$ python3.11 -m podman_compose version
podman-compose version 1.6.0
podman version 4.9.4-rhel
[opc@opaf-01 OPAF_INSTALLATION]$
|
This time, the deployment proceeds through image verification, Quickstart configuration, container startup, and database health checks, completing with the standard summary table and the Agent Factory web UI URL.
|
[opc@opaf-01 OPAF_INSTALLATION]$ make all
bash deploy.sh; \
▗▄▖ ▗▄▄▖ ▗▄▖ ▗▄▄▖▗▖ ▗▄▄▄▖
▐▌ ▐▌▐▌ ▐▌▐▌ ▐▌▐▌ ▐▌ ▐▌
▐▌ ▐▌▐▛▀▚▖▐▛▀▜▌▐▌ ▐▌ ▐▛▀▀▘
▝▚▄▞▘▐▌ ▐▌▐▌ ▐▌▝▚▄▄▖▐▙▄▄▖▐▙▄▄▖
▗▄▖ ▗▄▄▖▗▄▄▄▖▗▖ ▗▖▗▄▄▄▖ ▗▄▄▄▖ ▗▄▖ ▗▄▄▖▗▄▄▄▖▗▄▖ ▗▄▄▖▗▖ ▗▖
▐▌ ▐▌▐▌ ▐▌ ▐▛▚▖▐▌ █ ▐▌ ▐▌ ▐▌▐▌ █ ▐▌ ▐▌▐▌ ▐▌▝▚▞▘
▐▛▀▜▌▐▌▝▜▌▐▛▀▀▘▐▌ ▝▜▌ █ ▐▛▀▀▘▐▛▀▜▌▐▌ █ ▐▌ ▐▌▐▛▀▚▖ ▐▌
▐▌ ▐▌▝▚▄▞▘▐▙▄▄▖▐▌ ▐▌ █ ▐▌ ▐▌ ▐▌▝▚▄▄▖ █ ▝▚▄▞▘▐▌ ▐▌ ▐▌
✓ Image 'localhost/applied-ai-label:26.4.0.0.0' found.
✓ Image 'localhost/applied-ai-label:26.4.0.0.0' found.
✓ Image 'container-registry.oracle.com/database/free:23.7.0.0' found.
Select installation mode:
1) prod
2) quickstart
Selection: 2
You have chosen Quickstart mode. Confirm? (yes/no):
yes
Deploying Oracle AI Database Private Agent Factory in Quickstart mode...
Quickstart fresh install needs a database admin password for one-time local DB bootstrap.
Enter quickstart database admin password:
Re-enter quickstart database admin password:
Select Agent Factory web UI access:
1) Private to this host: the web UI is reachable only from this machine.
2) Reachable from other hosts: the web UI listens on all host interfaces, subject to network and firewall rules.
Selection: 2
You have chosen Reachable from other hosts. Confirm? (yes/no):
yes
Configured Agent Factory web UI access as Reachable from other hosts.
Confirming container 'oracle-applied-ai-label' is in a running state...
- Waiting for container to be ready...
✓ Container is confirmed to be running.
- Configuring application container 'oracle-applied-ai-label'...
- Configuring application container: oracle-applied-ai-label...
✓ crond service started in oracle-applied-ai-label.
✓ Application container oracle-applied-ai-label configured successfully.
Initiating startup for oracle-applied-ai-label container...
Initiating startup for oracle-database container...
✓ oracle-database container is UP and RUNNING.
- Waiting for oracle-database to become healthy...
✓ oracle-applied-ai-label container is UP and RUNNING.
- Please wait while the application is being set up within oracle-applied-ai-label container...
- Waiting for oracle-database to become healthy...
- Waiting for oracle-database to become healthy...
- Waiting for oracle-database to become healthy...
- Waiting for oracle-database to become healthy...
✓ Container 'oracle-database' is HEALTHY.
✓ Application setup successfully within the container 'oracle-applied-ai-label'.
+------------------------------------------------+------------+
| Stage | Status |
+------------------------------------------------+------------+
| Stopping Oracle Private AI Agent agent_factory | Successful |
+------------------------------------------------+------------+
| Storing App Secret Key | Successful |
+------------------------------------------------+------------+
| Database Migration | Successful |
+------------------------------------------------+------------+
| Starting Oracle Private AI Agent agent_factory | Successful |
+------------------------------------------------+------------+
| Configured Version Link | Successful |
+------------------------------------------------+------------+
The Oracle AI Database Private Agent Factory webapp can be accessed at:
https://opaf-01.*********.cnvcn01.oraclevcn.com:8080/agentFactory/
✓ Quickstart deployment complete.
Logs can be found at: ./deploy.log
[opc@opaf-01 OPAF_INSTALLATION]$
|
Takeaway
If make install times out waiting for oracle-applied-ai-label to become ready, don’t assume it’s a resource or health-check problem by default. Check whether make install (or deploy.sh) is failing earlier for an unrelated reason – in this case, a missing podman-compose module – that only manifests downstream as a container timeout. Running the install command directly, rather than relying solely on the wrapper’s summary output, is the fastest way to see the real traceback.
In the next blog, I will show how you can test the Deep Data Research Agent.
For more information, check out our Oracle Services, or contact us today, and one of our experts will be in touch.