Deploy From a Container Image

Deploy a fresh production Agent Factory instance directly from a bootstrapped container image by using Podman.

Use this procedure only for the single-image deployment workflow. Replace <image-reference> with the supplied image tag or registry reference.

Before You Begin

Prepare the following before you start the container:

Caution: Do not put passwords, API keys, private keys, API key fingerprints, or service-account JSON in runtime.env. Store secrets in Podman secrets.

The container uses these default input locations:

Input Default in-container location
Runtime environment file /etc/agent-factory/runtime.env
Podman secrets directory /run/secrets
Administrator password /run/secrets/agent_factory_admin_password
Database password /run/secrets/agent_factory_db_password
Database wallet ZIP /run/secrets/db_wallet.zip

Prepare an Image for an Air-Gapped Environment

On a machine with access to Oracle Container Registry, pull the Agent Factory image and save it as a tar file. Replace <image-tag> with the supplied image tag. For example, use 26.7.0.

podman pull container-registry.oracle.com/database/applied-ai:<image-tag>
podman save -o image.tar container-registry.oracle.com/database/applied-ai:<image-tag>

Transfer image.tar to the air-gapped machine. On that machine, load the image before you run the container:

podman load -i image.tar

Prepare Runtime Inputs

Create a directory for the runtime environment file, then create the required Podman secrets.

mkdir -p config
printf '%s' '<admin-password>' | podman secret create agent_factory_admin_password -
printf '%s' '<db-password>' | podman secret create agent_factory_db_password -

For Wallet mode, also create the database wallet secret:

podman secret create db_wallet.zip <wallet.zip>

Save one of the following examples as config/runtime.env. Only AGENT_FACTORY_* runtime configuration names are supported.

Details Mode

Use Details mode when you connect to the database with its host, port, service name, and protocol.

AGENT_FACTORY_MODE=prod
AGENT_FACTORY_SILENT_INSTALL=true
AGENT_FACTORY_ADMIN_USERNAME=admin@example.com
AGENT_FACTORY_DB_CONNECTION_TYPE=Details
AGENT_FACTORY_DB_USERNAME=<DB_USER>
AGENT_FACTORY_DB_IS_AIR_GAPPED=no
AGENT_FACTORY_DB_USES_WALLET=no
AGENT_FACTORY_DB_WALLET_HAS_OCI_CERTIFICATES=no
AGENT_FACTORY_DB_PROTOCOL=TCP
AGENT_FACTORY_DB_HOST=<db-host>
AGENT_FACTORY_DB_PORT=1521
AGENT_FACTORY_DB_SERVICE_NAME=<db-service>
AGENT_FACTORY_BIND_HOST=0.0.0.0

Wallet Mode

Use Wallet mode when you connect to the database through the db_wallet.zip Podman secret.

Set AGENT_FACTORY_DB_SELECTED_TNS_ALIAS to an alias that ends in _tp or _tpurgent. We recommend _tpurgent for lower latency. Other aliases are not optimized for application DML operations. See Database Service Names for Autonomous AI Database.

AGENT_FACTORY_MODE=prod
AGENT_FACTORY_SILENT_INSTALL=true
AGENT_FACTORY_ADMIN_USERNAME=admin@example.com
AGENT_FACTORY_DB_CONNECTION_TYPE=Wallet
AGENT_FACTORY_DB_USERNAME=<DB_USER>
AGENT_FACTORY_DB_IS_AIR_GAPPED=no
AGENT_FACTORY_DB_USES_WALLET=yes
AGENT_FACTORY_DB_WALLET_HAS_OCI_CERTIFICATES=yes
AGENT_FACTORY_DB_SELECTED_TNS_ALIAS=<tns-alias>
AGENT_FACTORY_BIND_HOST=0.0.0.0

Run the Container

Create a new persistent volume for the deployment:

podman volume create agentfactory_selfcontained_mount

Run a Details mode deployment with the default input locations:

podman run -d \
  --name oracle-applied-ai-selfcontained \
  -p 8080:8080 \
  -v agentfactory_selfcontained_mount:/mount:Z \
  -v "$PWD/config/runtime.env:/etc/agent-factory/runtime.env:ro,Z" \
  --secret agent_factory_admin_password \
  --secret agent_factory_db_password \
  <image-reference>

For Wallet mode, add the wallet secret to the command:

--secret db_wallet.zip

Access the Application

Important: Wait for image bootstrapping to complete before accessing the application. Monitor the bootstrap status by running the following command:

podman logs -f oracle-applied-ai-selfcontained

The AGENT_FACTORY_BIND_HOST setting controls the interface on which the application binds inside the container. Use 0.0.0.0 for broad in-container binding or 127.0.0.1 for loopback binding.

Use Podman port publishing to control host access:

# Host-local access only
-p 127.0.0.1:8080:8080

# Access through host network interfaces
-p 8080:8080

If you configure an optional LLM during bootstrap, add only one provider’s AGENT_FACTORY_LLM_* settings and matching Podman secrets. Otherwise, configure LLMs after deployment. See Configure LLM.

Use Custom Runtime Locations

To mount the runtime environment file at a different in-container path, pass AGENT_FACTORY_RUNTIME_ENV_PATH with podman run. Do not put this setting inside runtime.env.

podman run -d \
  --name oracle-applied-ai-selfcontained \
  -p 8080:8080 \
  -e AGENT_FACTORY_RUNTIME_ENV_PATH=/agent-factory-input/runtime.env \
  -v agentfactory_selfcontained_mount:/mount:Z \
  -v "$PWD/config/runtime.env:/agent-factory-input/runtime.env:ro,Z" \
  --secret agent_factory_admin_password \
  --secret agent_factory_db_password \
  <image-reference>

When you use a custom runtime secrets directory instead of Podman secrets, mount the directory and pass its absolute in-container path with AGENT_FACTORY_RUNTIME_SECRETS_DIR.

Run a Fresh Deployment Again

To run a fresh installation, clear the existing database schemas and persistent mount data:

  1. Use a new runtime database user, or drop and re-create the existing runtime user and grant the required privileges again. This removes schemas from the earlier deployment. See Database Preparation and Grants.
  2. Use a new /mount volume. Alternatively, delete the existing volume and create it again to remove residual data. Reusing a volume reuses the persisted installation state.
podman rm -f oracle-applied-ai-selfcontained
podman volume create agentfactory_selfcontained_mount_new

To reuse the existing volume name after clearing its contents, run:

podman volume rm agentfactory_selfcontained_mount
podman volume create agentfactory_selfcontained_mount