OCI Deployment — Container Instances¶

Beta Documentation

OCI deployment support is in beta and has received limited testing. OCI deployment involves more manual configuration than Azure. Steps may require adjustment for your specific environment. Please report any issues or corrections to Caprus AI.

AgentCube connectors run on OCI Container Instances with an OCI Load Balancer handling TLS termination. Container Instances is Oracle's managed container service — simpler than OKE (Kubernetes) and appropriate for single-container deployments.

Prerequisites¶

OCI account with a compartment for AgentCube resources
OCI CLI installed and configured (oci setup config)
A VCN with at least one public subnet, or permissions to create one
A TLS certificate (from OCI Certificates service, Let's Encrypt, or your CA)
A registered domain name (recommended)

See Container Images & Specifications for image names, GHCR authentication, and resource requirements.

Step 1: Configure Networking¶

If you have an existing VCN and public subnet, skip to Step 2. Otherwise, create the required network resources:

Create VCN¶

oci network vcn create \
  --compartment-id {compartment_ocid} \
  --cidr-block "10.0.0.0/16" \
  --display-name "agentcube-vcn"

Note the VCN OCID from the response.

Create Internet Gateway¶

oci network internet-gateway create \
  --compartment-id {compartment_ocid} \
  --vcn-id {vcn_ocid} \
  --is-enabled true \
  --display-name "agentcube-igw"

Update Route Table¶

oci network route-table update \
  --rt-id {default_route_table_ocid} \
  --route-rules '[{
    "cidrBlock": "0.0.0.0/0",
    "networkEntityId": "{internet_gateway_ocid}"
  }]' \
  --force

Create Public Subnet¶

oci network subnet create \
  --compartment-id {compartment_ocid} \
  --vcn-id {vcn_ocid} \
  --cidr-block "10.0.1.0/24" \
  --display-name "agentcube-subnet"

Configure Security Rules¶

Allow inbound traffic on port 8080 (container), 443 (HTTPS), and 80 (HTTP redirect):

oci network security-list update \
  --security-list-id {default_security_list_ocid} \
  --ingress-security-rules '[
    {
      "protocol": "6",
      "source": "0.0.0.0/0",
      "tcpOptions": {"destinationPortRange": {"min": 443, "max": 443}}
    },
    {
      "protocol": "6",
      "source": "0.0.0.0/0",
      "tcpOptions": {"destinationPortRange": {"min": 80, "max": 80}}
    },
    {
      "protocol": "6",
      "source": "0.0.0.0/0",
      "tcpOptions": {"destinationPortRange": {"min": 8080, "max": 8080}}
    }
  ]' \
  --force

Step 2: Create the Container Instance¶

Save the following as containers.json:

[
  {
    "displayName": "agentcube-essbase",
    "imageUrl": "ghcr.io/caprusai/agentcube-essbase:{version}",
    "ports": [
      {
        "containerPort": 8080,
        "protocol": "TCP"
      }
    ],
    "environmentVariables": [
      {"name": "ESSBASE_SERVER_URL", "value": "https://{essbase_host}"},
      {"name": "ESSBASE_USERNAME",   "value": "{username}"},
      {"name": "ESSBASE_PASSWORD",   "value": "{password}"}
    ],
    "resourceConfig": {
      "vcpusLimit": 0.5,
      "memoryLimitInGBs": 1
    },
    "restartPolicy": "ALWAYS"
  }
]

Save the following as shape-config.json:

{
  "ocpus": 1,
  "memoryInGBs": 2
}

Create the container instance:

oci container-instances container-instance create \
  --availability-domain {availability_domain} \
  --compartment-id {compartment_ocid} \
  --shape CI.Standard.E4.Flex \
  --shape-config file://shape-config.json \
  --containers file://containers.json \
  --vnics '[{"subnetId": "{subnet_ocid}", "assignPublicIp": true}]' \
  --display-name "agentcube-essbase"

Note the private IP address of the container instance — you will need it when configuring the load balancer backend.

Minimum replicas

Container Instances do not auto-restart on failure unless restartPolicy is set to ALWAYS. Scale to zero is not supported — the instance runs continuously.

Sensitive credentials

OCI Vault can be used to store credentials securely. For evaluation deployments, environment variables are sufficient. See the OCI Vault documentation for production hardening.

Planning connector

For the Planning connector, replace the image and environment variables accordingly. See Environment Variables for the full reference.

Step 3: Create the Load Balancer¶

OCI Container Instances do not include a managed ingress or TLS termination — a separate Load Balancer is required. This is the primary difference from Azure Container Apps.

Create the Load Balancer¶

oci lb load-balancer create \
  --compartment-id {compartment_ocid} \
  --display-name "agentcube-lb" \
  --shape-name "flexible" \
  --shape-details '{"minimumBandwidthInMbps": 10, "maximumBandwidthInMbps": 10}' \
  --subnet-ids '["{subnet_ocid}"]'

Wait for the load balancer to reach ACTIVE state before continuing (typically 2–5 minutes):

oci lb load-balancer get \
  --load-balancer-id {load_balancer_ocid} \
  --query 'data."lifecycle-state"'

Note the load balancer's public IP address from the response.

Create the Backend Set¶

oci lb backend-set create \
  --load-balancer-id {load_balancer_ocid} \
  --name "agentcube-backends" \
  --policy "ROUND_ROBIN" \
  --health-checker-protocol "HTTP" \
  --health-checker-port 8080 \
  --health-checker-url-path "/health"

Add the Container Instance as a Backend¶

oci lb backend create \
  --load-balancer-id {load_balancer_ocid} \
  --backend-set-name "agentcube-backends" \
  --ip-address {container_instance_private_ip} \
  --port 8080

Step 4: Configure TLS¶

OCI Load Balancer requires you to supply the certificate and private key directly.

Option A: OCI Certificates Service (recommended for production)¶

If your certificate is managed through the OCI Certificates service:

oci lb certificate create \
  --load-balancer-id {load_balancer_ocid} \
  --certificate-name "agentcube-cert" \
  --certificate-id {oci_certificate_ocid}

Option B: Upload Certificate Directly¶

If using a certificate from Let's Encrypt, your CA, or a self-signed cert:

oci lb certificate create \
  --load-balancer-id {load_balancer_ocid} \
  --certificate-name "agentcube-cert" \
  --public-certificate file://certificate.pem \
  --private-key file://private.pem \
  --ca-certificate file://ca-bundle.pem

Let's Encrypt with Certbot

Certbot (certbot certonly --standalone -d {connector_hostname}) can generate a free trusted certificate. Renew every 90 days and re-upload to the load balancer.

Create the HTTPS Listener¶

oci lb listener create \
  --load-balancer-id {load_balancer_ocid} \
  --name "https-listener" \
  --default-backend-set-name "agentcube-backends" \
  --port 443 \
  --protocol "HTTPS" \
  --ssl-configuration '{
    "certificateName": "agentcube-cert",
    "protocols": ["TLSv1.2", "TLSv1.3"]
  }'

Create the HTTP Listener (Redirect to HTTPS)¶

oci lb listener create \
  --load-balancer-id {load_balancer_ocid} \
  --name "http-listener" \
  --default-backend-set-name "agentcube-backends" \
  --port 80 \
  --protocol "HTTP"

Step 5: Configure DNS (Optional)¶

Point your domain at the load balancer's public IP. Using OCI DNS:

oci dns record rrset update \
  --zone-name-or-id {zone_name} \
  --domain "{connector_hostname}" \
  --rtype "A" \
  --items '[{
    "domain": "{connector_hostname}",
    "rtype": "A",
    "ttl": 300,
    "rdata": "{load_balancer_public_ip}"
  }]' \
  --force

Step 6: Verify¶

curl https://{connector_hostname}/health

See Verification for the expected response and full verification checklist.

Comparison with Azure Container Apps¶

	OCI Container Instances	Azure Container Apps
TLS termination	Manual — separate Load Balancer required	Built-in
Managed certificates	Manual certificate upload or OCI Certificates	Automatic via Azure
Networking setup	VCN, subnet, security rules required	More abstracted
Autoscaling	Not supported (fixed instance count)	Built-in
Cold starts	N/A — always running	Possible if scaled to zero