Skip to content

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.

  • 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.

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.

PowerShell:

Terminal window
@'
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {"Service": "ecs-tasks.amazonaws.com"},
"Action": "sts:AssumeRole"
}]
}
'@ | Set-Content -Path trust-ecs-tasks.json
aws iam create-role --role-name ecsTaskExecutionRole --assume-role-policy-document file://trust-ecs-tasks.json
aws iam attach-role-policy --role-name ecsTaskExecutionRole --policy-arn arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy

bash:

Terminal window
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/AmazonECSTaskExecutionRolePolicy

PowerShell:

Terminal window
@'
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {"Service": "ecs.amazonaws.com"},
"Action": "sts:AssumeRole"
}]
}
'@ | Set-Content -Path trust-ecs.json
aws iam create-role --role-name ecsInfrastructureRole --assume-role-policy-document file://trust-ecs.json
aws iam attach-role-policy --role-name ecsInfrastructureRole --policy-arn arn:aws:iam::aws:policy/AmazonECSInfrastructureRoleforExpressGatewayServices

bash:

Terminal window
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/AmazonECSInfrastructureRoleforExpressGatewayServices

Step 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.

ECS requires registry credentials to pull from ghcr.io. Create a GitHub Personal Access Token with read:packages scope, then store it:

PowerShell:

Terminal window
@'
{"username":"{github_username}","password":"{github_pat}"}
'@ | Set-Content -Path ghcr-credentials.json
aws secretsmanager create-secret --name agentcube/ghcr-credentials --secret-string file://ghcr-credentials.json --region {region}
Remove-Item ghcr-credentials.json

bash:

Terminal window
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.

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=admin with AGENTCUBE_AUTH_MODE=delegated_basic. The connector holds no credentials.
  • User lane: AGENTCUBE_CONNECTOR_MODE=user with AGENTCUBE_AUTH_MODE=internal (single sign-on through the Context Engine). This lane needs the AGENTCUBE_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:

Terminal window
@'
{
"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 @ecsArgs

bash:

Terminal window
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:

  1. 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}
  2. 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}
  3. 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.

  4. 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.json
    aws route53 change-resource-record-sets --hosted-zone-id {hosted_zone_id} --change-batch file://alias-record.json

    bash:

    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
    }
    }
    }]
    }'

PowerShell:

Terminal window
Invoke-RestMethod https://{connector_hostname}/health

bash:

Terminal window
curl https://{connector_hostname}/health

In 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.