AWS Deployment — ECS Express Mode
AgentCube containers deploy on AWS using ECS Express Mode — the recommended approach for container deployments on AWS. A single command provisions the ECS service on Fargate, an Application Load Balancer, auto-scaling, and networking automatically. No separate ALB, target group, or certificate management is required.
Prerequisites
Section titled “Prerequisites”- AWS account with permissions to manage ECS, IAM, and Secrets Manager
- AWS CLI installed and configured (
aws configure) - Default VPC with at least two public subnets across two Availability Zones
- A registered domain name (recommended for a stable connector URL)
See Container Images & Specifications for image names, GHCR authentication, and resource requirements.
Step 1: Create the Required IAM Roles
Section titled “Step 1: Create the Required IAM Roles”Each step gives the AWS CLI commands for PowerShell 7 first, then for bash. The PowerShell variants pass JSON through a file (file://) so no quoting or line continuation is needed.
ECS Express Mode requires two IAM roles — one for task execution (image pull, logging, secrets) and one that allows ECS to manage the underlying infrastructure (ALB, auto-scaling, networking) on your behalf.
Task Execution Role
Section titled “Task Execution Role”PowerShell:
@'{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Principal": {"Service": "ecs-tasks.amazonaws.com"}, "Action": "sts:AssumeRole" }]}'@ | Set-Content -Path trust-ecs-tasks.jsonaws iam create-role --role-name ecsTaskExecutionRole --assume-role-policy-document file://trust-ecs-tasks.jsonaws iam attach-role-policy --role-name ecsTaskExecutionRole --policy-arn arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicybash:
aws iam create-role \ --role-name ecsTaskExecutionRole \ --assume-role-policy-document '{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Principal": {"Service": "ecs-tasks.amazonaws.com"}, "Action": "sts:AssumeRole" }] }'
aws iam attach-role-policy \ --role-name ecsTaskExecutionRole \ --policy-arn arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicyInfrastructure Role
Section titled “Infrastructure Role”PowerShell:
@'{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Principal": {"Service": "ecs.amazonaws.com"}, "Action": "sts:AssumeRole" }]}'@ | Set-Content -Path trust-ecs.jsonaws iam create-role --role-name ecsInfrastructureRole --assume-role-policy-document file://trust-ecs.jsonaws iam attach-role-policy --role-name ecsInfrastructureRole --policy-arn arn:aws:iam::aws:policy/AmazonECSInfrastructureRoleforExpressGatewayServicesbash:
aws iam create-role \ --role-name ecsInfrastructureRole \ --assume-role-policy-document '{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Principal": {"Service": "ecs.amazonaws.com"}, "Action": "sts:AssumeRole" }] }'
aws iam attach-role-policy \ --role-name ecsInfrastructureRole \ --policy-arn arn:aws:iam::aws:policy/AmazonECSInfrastructureRoleforExpressGatewayServicesStep 2: Store Credentials in Secrets Manager
Section titled “Step 2: Store Credentials in Secrets Manager”Store secrets in Secrets Manager rather than passing them as plaintext environment variables: the GitHub Container Registry pull credentials, the Context Engine’s database URL and credential key, and, for a user-lane connector, its OCI client secret and signing key. The admin-lane connector deployed below holds no Oracle credentials: it uses a delegated credential, one named Oracle account whose username and password you enter when you register the connector in the Context Engine, which stores them encrypted. Every user of that connector shares that account.
GHCR pull credentials
Section titled “GHCR pull credentials”ECS requires registry credentials to pull from ghcr.io. Create a GitHub Personal Access Token with read:packages scope, then store it:
PowerShell:
@'{"username":"{github_username}","password":"{github_pat}"}'@ | Set-Content -Path ghcr-credentials.jsonaws secretsmanager create-secret --name agentcube/ghcr-credentials --secret-string file://ghcr-credentials.json --region {region}Remove-Item ghcr-credentials.jsonbash:
aws secretsmanager create-secret \ --name agentcube/ghcr-credentials \ --secret-string '{"username":"{github_username}","password":"{github_pat}"}' \ --region {region}Note the ARN returned — you will reference it in the next step.
Step 3: Deploy with ECS Express Mode
Section titled “Step 3: Deploy with ECS Express Mode”Each connector runs in one of two lanes. The recommended pairing, which is the same for Essbase, Planning and FCCS:
- Admin lane:
AGENTCUBE_CONNECTOR_MODE=adminwithAGENTCUBE_AUTH_MODE=delegated_basic. The connector holds no credentials. - User lane:
AGENTCUBE_CONNECTOR_MODE=userwithAGENTCUBE_AUTH_MODE=internal(single sign-on through the Context Engine). This lane needs theAGENTCUBE_INTERNAL_*,OCI_*and signing-key variables listed in Environment Variables, and SSO turned on in the Context Engine.
See Auth Modes for how to choose. The following single command deploys the Essbase admin lane and provisions the ECS service, ALB, HTTPS endpoint, and auto-scaling:
PowerShell:
@'{ "image": "ghcr.io/caprusai/agentcube-essbase:{version}", "containerPort": 8080, "repositoryCredentials": {"credentialsParameter": "arn:aws:secretsmanager:{region}:{account_id}:secret:agentcube/ghcr-credentials"}, "environment": [ {"name": "AGENTCUBE_CONNECTOR_MODE", "value": "admin"}, {"name": "AGENTCUBE_AUTH_MODE", "value": "delegated_basic"}, {"name": "ESSBASE_SERVER_URL", "value": "https://{essbase_host}"} ]}'@ | Set-Content -Path essbase-container.json$ecsArgs = @( "ecs", "create-express-gateway-service", "--service-name", "agentcube-essbase", "--execution-role-arn", "arn:aws:iam::{account_id}:role/ecsTaskExecutionRole", "--infrastructure-role-arn", "arn:aws:iam::{account_id}:role/ecsInfrastructureRole", "--primary-container", "file://essbase-container.json", "--cpu", "256", "--memory", "512", "--health-check-path", "/health", "--scaling-target", "minTaskCount=1,maxTaskCount=4", "--region", "{region}")aws @ecsArgsbash:
aws ecs create-express-gateway-service \ --service-name agentcube-essbase \ --execution-role-arn arn:aws:iam::{account_id}:role/ecsTaskExecutionRole \ --infrastructure-role-arn arn:aws:iam::{account_id}:role/ecsInfrastructureRole \ --primary-container \ image=ghcr.io/caprusai/agentcube-essbase:{version},\ containerPort=8080,\ repositoryCredentials={credentialsParameter=arn:aws:secretsmanager:{region}:{account_id}:secret:agentcube/ghcr-credentials},\ environment=[{name=AGENTCUBE_CONNECTOR_MODE,value=admin},{name=AGENTCUBE_AUTH_MODE,value=delegated_basic},{name=ESSBASE_SERVER_URL,value=https://{essbase_host}}] \ --cpu 256 \ --memory 512 \ --health-check-path /health \ --scaling-target minTaskCount=1,maxTaskCount=4 \ --region {region}AWS returns a service ARN and a public HTTPS endpoint URL (servicename.ecs.{region}.on.aws). The connector is accessible at that URL within a few minutes.
A connector left on AGENTCUBE_CONNECTOR_MODE=user with the default AGENTCUBE_AUTH_MODE=basic refuses to start. Essbase defaults to user, so always set both variables. delegated_basic also refuses to start if ESSBASE_USERNAME / ESSBASE_PASSWORD are set.
Step 4: Configure a Custom Domain (Optional)
Section titled “Step 4: Configure a Custom Domain (Optional)”The AWS-provided URL works immediately with HTTPS. To use your own domain:
-
Request an ACM certificate for your domain in the same region:
PowerShell:
Terminal window aws acm request-certificate --domain-name {connector_hostname} --validation-method DNS --region {region}bash:
Terminal window aws acm request-certificate \--domain-name {connector_hostname} \--validation-method DNS \--region {region} -
Add the DNS validation records provided by ACM to your DNS provider. Wait until status shows
ISSUED:PowerShell:
Terminal window aws acm describe-certificate --certificate-arn {certificate_arn} --query 'Certificate.Status' --region {region}bash:
Terminal window aws acm describe-certificate \--certificate-arn {certificate_arn} \--query 'Certificate.Status' \--region {region} -
In the AWS Console, navigate to ECS → Services → agentcube-essbase → Resources → Load Balancer → Listener → Edit. Add your ACM certificate and a Host header condition for your domain.
-
Create a Route 53 alias record pointing to the ALB DNS name:
PowerShell:
Terminal window @'{"Changes": [{"Action": "CREATE","ResourceRecordSet": {"Name": "{connector_hostname}","Type": "A","AliasTarget": {"HostedZoneId": "{alb_hosted_zone_id}","DNSName": "{alb_dns_name}","EvaluateTargetHealth": true}}}]}'@ | Set-Content -Path alias-record.jsonaws route53 change-resource-record-sets --hosted-zone-id {hosted_zone_id} --change-batch file://alias-record.jsonbash:
Terminal window aws route53 change-resource-record-sets \--hosted-zone-id {hosted_zone_id} \--change-batch '{"Changes": [{"Action": "CREATE","ResourceRecordSet": {"Name": "{connector_hostname}","Type": "A","AliasTarget": {"HostedZoneId": "{alb_hosted_zone_id}","DNSName": "{alb_dns_name}","EvaluateTargetHealth": true}}}]}'
Step 5: Verify
Section titled “Step 5: Verify”PowerShell:
Invoke-RestMethod https://{connector_hostname}/healthbash:
curl https://{connector_hostname}/healthIn delegated and SSO modes the connector always reports "status": "healthy"; watch backend.status for Oracle reachability. backend_connected appears only in basic mode. See Verification for the expected response and full verification checklist.
After the Context Engine is running, install your license: sign in to the admin console, open Admin & Security → License, paste the key Caprus AI issued into License key and select Save. The Context Engine must reach https://licensing.caprus.ai over outbound HTTPS (443). Then register each connector in the Context Engine as a connected system with the matching auth mode.