Deploy From a Container Image

Deploy a self-contained Agent Factory production image with Podman and configure its database, runtime settings, secrets, and persistent storage.

On its first start, the image bootstraps Agent Factory from a runtime configuration file and mounted secret files. Application data and installation state are stored in a persistent volume.

Replace <image-reference> with the complete Oracle Container Registry image reference, including its tag.

Prerequisites

Prepare the following before you start the container:

An Oracle account that has accepted the license agreement for the Agent Factory image in Oracle Container Registry.
Podman and an Agent Factory image reference from Oracle Container Registry.
A persistent Podman volume mounted at /mount.
A runtime.env file containing non-secret runtime configuration.
Podman secrets for the initial administrator password and database password.
A target pluggable database (PDB) with an Agent Factory runtime user and its read-only companion user.

Set `MAX_STRING_SIZE` to `EXTENDED`

The target database must use EXTENDED for MAX_STRING_SIZE. Connect to the target PDB as SYSDBA and check its current value:

SELECT value FROM v$parameter WHERE name = 'max_string_size';

If the value is not EXTENDED, run the following statements as SYSDBA. This procedure restarts the database.

ALTER SYSTEM SET max_string_size=extended SCOPE=SPFILE;

SHUTDOWN NORMAL;
STARTUP UPGRADE;

@$ORACLE_HOME/rdbms/admin/utl32k.sql

SHUTDOWN IMMEDIATE;
STARTUP;

@$ORACLE_HOME/rdbms/admin/utlrp.sql

Create the Database Users

The read-only user must be named AAI_RO_<DB_USER> and use the same password as the runtime user. Connect to the target PDB as an administrative user, replace the placeholders, and run the following statements:

CREATE USER <DB_USER> IDENTIFIED BY "<DB_PASSWORD>"
  DEFAULT TABLESPACE USERS
  QUOTA UNLIMITED ON USERS;

GRANT CONNECT, RESOURCE TO <DB_USER>;
GRANT CREATE SESSION TO <DB_USER> WITH ADMIN OPTION;
GRANT CREATE TABLE, CREATE SYNONYM, CREATE SEQUENCE, CREATE TRIGGER TO <DB_USER>;
GRANT CREATE USER, DROP USER TO <DB_USER>;
GRANT READ, WRITE ON DIRECTORY DATA_PUMP_DIR TO <DB_USER>;
GRANT SELECT ON V_$PARAMETER TO <DB_USER>;

CREATE USER AAI_RO_<DB_USER> IDENTIFIED BY "<DB_PASSWORD>" ACCOUNT UNLOCK;
GRANT CREATE SESSION TO AAI_RO_<DB_USER>;

See Database Preparation and Grants for validation and Autonomous Database guidance.

Create a Valid Administrator Password

The initial administrator password must have at least eight characters and include:

An uppercase ASCII letter
A decimal digit
A character from -+_!@#$%^&*.,?

Quick Start

Create a persistent volume, create the required Podman secrets, and create a directory for the runtime configuration file. Replace the placeholder values with values for your environment.

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

Details Mode

Use Details mode to connect by using a database host, port, and service name. Save the following configuration as config/runtime.env:

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

Start the container:

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>

Wallet Mode

Use Wallet mode to connect through a database wallet. Create the wallet secret:

podman secret create db_wallet.zip <wallet.zip>

Save the following configuration as config/runtime.env. Replace <tns-alias> with the selected TNS alias from the wallet.

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

Start the container with the wallet secret:

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 \
  --secret db_wallet.zip \
  <image-reference>

Access and Verify the Deployment

Monitor the bootstrap process until it completes:

podman logs -f oracle-applied-ai-selfcontained

Important: Do not access the web interface until bootstrap is complete.

After bootstrap completes, open https://<host>:8080 and sign in with the administrator username from runtime.env and the password stored in the agent_factory_admin_password secret.

To expose the web interface only on the local host, use the following port mapping instead of -p 8080:8080:

-p 127.0.0.1:8080:8080

Persistence and Repeat Runs

The /mount volume stores application data and installation state. To restart an existing deployment, start a container with the same volume.

For a clean deployment, use a new volume or remove the old container and its volume before recreating the volume. You must also use new runtime and read-only database users, or drop and re-create the existing users before starting the image.

podman rm -f oracle-applied-ai-selfcontained
podman volume rm agentfactory_selfcontained_mount
podman volume create agentfactory_selfcontained_mount

Runtime Configuration and Secrets

The default in-container input locations are:

Input	Default location
Runtime configuration	`/etc/agent-factory/runtime.env`
Secret directory	`/run/secrets`
Administrator password	`/run/secrets/agent_factory_admin_password`
Database password	`/run/secrets/agent_factory_db_password`
Database wallet	`/run/secrets/db_wallet.zip`

To use a custom runtime configuration location, pass the path to the container and mount the file at that path:

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>

If you mount a secrets directory instead of using Podman secrets, set AGENT_FACTORY_RUNTIME_SECRETS_DIR to its absolute in-container path.

Configure an Optional LLM During Bootstrap

LLM bootstrap is optional. Leave AGENT_FACTORY_LLM_PROVIDER unset to install the application without an LLM, and configure an LLM later from the web interface. See Configure LLM.

To configure an LLM during bootstrap, select one provider with AGENT_FACTORY_LLM_PROVIDER. Add its non-secret settings to runtime.env, and pass any credential files as Podman secrets.

Provider	Typical required settings	Optional or required secret file
OCI Generative AI	Model ID, service endpoint, and compartment ID	API key mode also uses fingerprint and private key files.
vLLM	Model ID, host, and port	`agent_factory_llm_vllm_api_key` when required.
OpenAI	Model ID	`agent_factory_llm_openai_api_key`.
OpenAI-compatible	Model ID and base URL	`agent_factory_llm_openai_compatible_api_key` when required.
Oracle Private AI Services	Model ID and base URL	API key and CA files when required.
Ollama	Model ID, host, and port	None.
Google Gemini	Model ID and credentials type	API key or service account JSON.

For example, to configure OpenAI during bootstrap, add these values to runtime.env:

AGENT_FACTORY_LLM_PROVIDER=openai
AGENT_FACTORY_LLM_NAME=llm_model_entry
AGENT_FACTORY_LLM_OPENAI_MODEL_ID=<model-id>
AGENT_FACTORY_LLM_OPENAI_API_KEY_FILE=agent_factory_llm_openai_api_key

Create the matching secret:

printf '%s' '<openai-api-key>' | podman secret create agent_factory_llm_openai_api_key -

Add --secret agent_factory_llm_openai_api_key to the podman run command.

Configuration Reference

Use the following variables in runtime.env. Secret-file values can be absolute paths or file names in the runtime secrets directory.

Core Keys

Key	Required	Description
`AGENT_FACTORY_MODE`	Yes	Set to `prod`.
`AGENT_FACTORY_SILENT_INSTALL`	Yes	Set to `true` for bootstrap installation.
`AGENT_FACTORY_ADMIN_USERNAME`	Yes	Initial administrator username or email address.

Database Keys

Key	Required	Description
`AGENT_FACTORY_DB_CONNECTION_TYPE`	Yes	Set to `Details` or `Wallet`.
`AGENT_FACTORY_DB_USERNAME`	Yes	Runtime database user.
`AGENT_FACTORY_DB_IS_AIR_GAPPED`	Yes	Set to `yes` or `no`.
`AGENT_FACTORY_DB_USES_WALLET`	When not air-gapped	Set to `yes` for Wallet mode or `no` for Details mode.
`AGENT_FACTORY_DB_WALLET_HAS_OCI_CERTIFICATES`	When using a wallet	Indicates whether the wallet contains OCI certificates. Set to `yes` or `no`.
`AGENT_FACTORY_DB_PROTOCOL`	Details mode	Set to `TCP` or `TCPS`.
`AGENT_FACTORY_DB_HOST`	Details mode	Database host.
`AGENT_FACTORY_DB_PORT`	Details mode	Database listener port.
`AGENT_FACTORY_DB_SERVICE_NAME`	Details mode	Database service name.
`AGENT_FACTORY_DB_SELECTED_TNS_ALIAS`	Wallet mode	TNS alias in the supplied wallet.

Web and Operational Keys

Key	Default	Description
`AGENT_FACTORY_BIND_HOST`	`0.0.0.0`	Application bind host inside the container.
`AGENT_FACTORY_CERT_FQDN`	Unset	Certificate fully qualified domain name override.
`AGENT_FACTORY_CERT_IP_ADDRESS`	Unset	Certificate IP address override.
`AGENT_FACTORY_ENABLE_SWAGGER`	Unset	Swagger enablement setting.
`AGENT_FACTORY_STATE_POLL_INTERVAL_SECONDS`	`5`	Bootstrap state polling interval.
`AGENT_FACTORY_API_READY_TIMEOUT_SECONDS`	`600`	Local API availability timeout.
`AGENT_FACTORY_INSTALL_TIMEOUT_SECONDS`	`1800`	Installation completion timeout.
`AGENT_FACTORY_READY_TIMEOUT_SECONDS`	`600`	Final readiness timeout.
`AGENT_FACTORY_HTTP_PROXY`	Unset	HTTP proxy.
`AGENT_FACTORY_HTTPS_PROXY`	Unset	HTTPS proxy.
`AGENT_FACTORY_NO_PROXY`	Unset	No-proxy host list.

LLM Keys

Configure at most one LLM provider during bootstrap.

Key	Required	Description
`AGENT_FACTORY_LLM_PROVIDER`	No	Set to `oci`, `vllm`, `openai`, `openai_compatible`, `private_ai_services`, `ollama`, or `google`.
`AGENT_FACTORY_LLM_NAME`	No	LLM configuration name. The default is `llm_model_entry`.

OCI Generative AI Keys

Key	Required	Description
`AGENT_FACTORY_LLM_OCI_MODEL_ID`	Yes	OCI model ID.
`AGENT_FACTORY_LLM_OCI_SERVICE_ENDPOINT`	Yes	OCI Generative AI service endpoint.
`AGENT_FACTORY_LLM_OCI_COMPARTMENT_ID`	Yes	OCI compartment OCID.
`AGENT_FACTORY_LLM_OCI_USER_OCID`	API key mode	OCI user OCID.
`AGENT_FACTORY_LLM_OCI_FINGERPRINT_FILE`	API key mode	Fingerprint secret file. The default name is `agent_factory_llm_oci_fingerprint`.
`AGENT_FACTORY_LLM_OCI_TENANCY_OCID`	API key mode	OCI tenancy OCID.
`AGENT_FACTORY_LLM_OCI_REGION`	API key mode	OCI region.
`AGENT_FACTORY_LLM_OCI_PRIVATE_KEY_FILE`	API key mode	Private key secret file. The default name is `agent_factory_llm_oci_private_key.pem`.

vLLM Keys

Key	Required	Description
`AGENT_FACTORY_LLM_VLLM_MODEL_ID`	Yes	Model ID.
`AGENT_FACTORY_LLM_VLLM_HOST`	Yes	vLLM host or base host.
`AGENT_FACTORY_LLM_VLLM_PORT`	Yes	vLLM port.
`AGENT_FACTORY_LLM_VLLM_API_KEY_FILE`	No	API key secret file when required. The default name is `agent_factory_llm_vllm_api_key`.

OpenAI Keys

Key	Required	Description
`AGENT_FACTORY_LLM_OPENAI_MODEL_ID`	Yes	OpenAI model ID.
`AGENT_FACTORY_LLM_OPENAI_API_KEY_FILE`	Yes	API key secret file. The default name is `agent_factory_llm_openai_api_key`.

OpenAI-Compatible Keys

Key	Required	Description
`AGENT_FACTORY_LLM_OPENAI_COMPATIBLE_MODEL_ID`	Yes	Model ID.
`AGENT_FACTORY_LLM_OPENAI_COMPATIBLE_BASE_URL`	Yes	OpenAI-compatible base URL.
`AGENT_FACTORY_LLM_OPENAI_COMPATIBLE_API_KEY_FILE`	No	API key secret file when required. The default name is `agent_factory_llm_openai_compatible_api_key`.

Oracle Private AI Services Keys

Key	Required	Description
`AGENT_FACTORY_LLM_PRIVATE_AI_SERVICES_MODEL_ID`	Yes	Model ID.
`AGENT_FACTORY_LLM_PRIVATE_AI_SERVICES_BASE_URL`	Yes	Service base URL.
`AGENT_FACTORY_LLM_PRIVATE_AI_SERVICES_API_KEY_FILE`	No	API key secret file when required. The default name is `agent_factory_llm_private_ai_services_api_key`.
`AGENT_FACTORY_LLM_PRIVATE_AI_SERVICES_CA_FILE`	No	Custom CA secret file when required. The default name is `agent_factory_llm_private_ai_services_ca.pem`.

Ollama Keys

Key	Required	Description
`AGENT_FACTORY_LLM_OLLAMA_MODEL_ID`	Yes	Ollama model ID.
`AGENT_FACTORY_LLM_OLLAMA_HOST`	Yes	Ollama host.
`AGENT_FACTORY_LLM_OLLAMA_PORT`	Yes	Ollama port.

Google Gemini Keys

Key	Required	Description
`AGENT_FACTORY_LLM_GOOGLE_MODEL_ID`	Yes	Google Gemini model ID.
`AGENT_FACTORY_LLM_GOOGLE_CREDENTIALS_TYPE`	Yes	Set to `API_KEY` or `GOOGLE_SERVICE_ACCOUNT`.
`AGENT_FACTORY_LLM_GOOGLE_API_KEY_FILE`	API key mode	API key secret file. The default name is `agent_factory_llm_google_api_key`.
`AGENT_FACTORY_LLM_GOOGLE_REGION`	Service account mode	Google region.
`AGENT_FACTORY_LLM_GOOGLE_SERVICE_ACCOUNT_FILE`	Service account mode	Service account JSON secret file. The default name is `agent_factory_llm_google_service_account.json`.