Self-host Intelligence on AWS ECS/Fargate

Deploy CopilotKit Intelligence in your AWS account with the versioned ECS/Fargate bundle and its cpki-ecs command. You start with your own network, databases, secrets, and OIDC provider. You finish with the Intelligence dashboard behind HTTPS, an authenticated session, and a runtime connected to your deployment.

What the bundle deploys#

The bundle uses the same released Intelligence service images as the Helm chart. It pins each first-party task image to a digest from release-manifest.json.

All four services run in private subnets with public IP assignment disabled. The embeddings service runs even when the deployment has no Memory entitlement; app API requires its provider configuration at startup. The composite image is not an ECS task in this bundle.

The three stacks do not create your VPC, PostgreSQL, Redis, OIDC provider, certificate, KMS keys, secret values, or application DNS records.

Before you start#

Release access and tools#

Obtain copilot-intelligence-ecs-<version>.tar.gz and release-manifest.json from the same release. The Intelligence GitHub releases require repository access. If you do not have access, contact your CopilotKit account team for the release bundle.

Install AWS CLI v2, Bash, jq, curl, tar, and Python 3 on the deployment machine. Use AWS credentials that can create CloudFormation stacks and their IAM roles, pass the generated task roles, and add ingress rules to the database and Redis security groups. Configuration validation uses read-only AWS APIs; deployment requires write access.

AWS resources#

The log key policy must allow the regional CloudWatch Logs service (logs.<region>.amazonaws.com) to use kms:Encrypt, kms:Decrypt, kms:ReEncrypt*, kms:GenerateDataKey*, and kms:Describe*, scoped to the encryption context for /ecs/<deploymentName>/*. The secret key policy must allow account IAM permissions so the task execution roles' kms:Decrypt grants take effect. The reference environment's substrate.yaml contains both policies.

The configurator calls sts:GetCallerIdentity, EC2 describe APIs for the supplied VPC, subnets, routes, and security groups, acm:DescribeCertificate, kms:DescribeKey, and secretsmanager:DescribeSecret. If you configure object storage, it also needs s3:GetBucketLocation. It checks the OIDC discovery document over HTTPS. It does not read secret values or test database credentials.

Secrets#

Create a separate Secrets Manager secret for each required field below. Encrypt every secret with the exact secretKmsKeyArn you will supply to the configurator. Configuration files contain ARNs; the tasks receive the secret values when they start.

For RDS, the service images include the CA bundle at /etc/cpki/rds-ca/global-bundle.pem. The bundle README documents sslmode=verify-full with that CA path. Match the Redis URL's TLS settings to your Redis service.

Analytics defaults to disabled. To enable it, set analyticsEnabled to true and supply both Timescale secret ARNs. The migration task receives the owner URL and the runtime URL; app API and realtime receive only the runtime URL. Both runtime services and the migration task must reach TimescaleDB.

First-install organization access#

An OIDC login does not grant organization access. Prepare a bootstrap file using the bundle's config/bootstrap.example.json. The following example creates one organization and grants membership to users whose OIDC groups claim contains the exact, case-sensitive value intelligence-users:

{
  "organizations": [
    {
      "slug": "my-organization",
      "name": "My Organization",
      "mappings": [
        {
          "role": "org_member",
          "claimName": "groups",
          "claimValue": "intelligence-users"
        }
      ]
    }
  ],
  "platformAdminMappings": [],
  "emergencyPlatformAdminGrants": []
}

Replace the organization and claim values with yours. Your IdP must emit the matching claim. The supported claim names are groups, roles, department, and entitlements; an email domain does not grant membership. Use the example file's platformAdminMappings shape if you also need to grant platform administration to a specific IdP group.

Base64-encode your file and store the resulting text as a Secrets Manager secret under the same secret KMS key:

base64 < bootstrap.json | tr -d '\n' > bootstrap.b64

Supply that secret's ARN as bootstrapConfigSecretArn. Deployment runs bootstrap after migrations. If no organization or access mapping exists, the UI reports that the deployment has not been bootstrapped. If the signed-in user matches no mapping, it reports that the user is not assigned to an organization.

Deploy and verify#

Run the following commands in Bash. Keep the same shell open so the paths set in the first step remain available.

export CPKI_VERSION=0.12.9
export CPKI_DEPLOY_DIR="$PWD"

tar -xzf "copilot-intelligence-ecs-${CPKI_VERSION}.tar.gz"
cd "copilot-intelligence-ecs-${CPKI_VERSION}"
export CPKI_CONFIG="$CPKI_DEPLOY_DIR/parameters.json"
export CPKI_MANIFEST="$CPKI_DEPLOY_DIR/release-manifest.json"

cmp ./release-manifest.json "$CPKI_MANIFEST"
./bin/cpki-ecs validate --offline

./bin/cpki-ecs configure --interactive --output "$CPKI_CONFIG"

cp ./config/example.parameters.json "$CPKI_DEPLOY_DIR/draft.parameters.json"
# Edit draft.parameters.json with your resource IDs, ARNs, and settings.
./bin/cpki-ecs configure \
  --from-json "$CPKI_DEPLOY_DIR/draft.parameters.json" \
  --output "$CPKI_CONFIG"

./bin/cpki-ecs deploy \
  --config "$CPKI_CONFIG" \
  --manifest "$CPKI_MANIFEST"

export AWS_REGION="$(jq -r '.region' "$CPKI_CONFIG")"
export CPKI_DEPLOYMENT_NAME="$(jq -r '.deploymentName' "$CPKI_CONFIG")"
export CPKI_UI_HOST="$(jq -r '.uiHostName' "$CPKI_CONFIG")"
export CPKI_REALTIME_HOST="$(jq -r '.realtimeHostName' "$CPKI_CONFIG")"

aws cloudformation describe-stacks \
  --region "$AWS_REGION" \
  --stack-name "${CPKI_DEPLOYMENT_NAME}-foundation" \
  --query 'Stacks[0].Outputs' --output table

./bin/cpki-ecs verify \
  --config "$CPKI_CONFIG" \
  --manifest "$CPKI_MANIFEST"

curl --fail "https://${CPKI_UI_HOST}/healthz"
curl --fail "https://${CPKI_UI_HOST}/api/health"
curl --fail "https://${CPKI_REALTIME_HOST}/health"

import { CopilotKitIntelligence } from "@copilotkit/runtime/v2";

const intelligence = new CopilotKitIntelligence({
  apiUrl: "https://intelligence.example.com",
  wsUrl: "wss://realtime.intelligence.example.com",
  apiKey: process.env.CPK_INTELLIGENCE_API_KEY!,
});

Evaluate with the reference environment#

The Intelligence source repository provides an AWS evaluation environment under deploy/ecs/examples/reference-environment/. The bundle root's README.md contains the full Quickstart: reference environment commands, including output-to-parameter wiring.

After the unpack step above, you can retrieve the source with the GitHub CLI authenticated to an account that has Intelligence repository access:

gh release download "v${CPKI_VERSION}" \
  --repo CopilotKit/Intelligence \
  --archive tar.gz \
  --output "$CPKI_DEPLOY_DIR/intelligence-source.tar.gz"

mkdir "$CPKI_DEPLOY_DIR/reference-source"
tar -xzf "$CPKI_DEPLOY_DIR/intelligence-source.tar.gz" \
  --strip-components=1 -C "$CPKI_DEPLOY_DIR/reference-source"

cd "$CPKI_DEPLOY_DIR/copilot-intelligence-ecs-${CPKI_VERSION}"
cp -R "$CPKI_DEPLOY_DIR/reference-source/deploy/ecs/examples" ./examples

Now follow Quickstart: reference environment in README.md from the extracted ECS bundle directory. Use your downloaded release manifest; you do not need to construct one from image tags.

The reference environment does not add a TimescaleDB instance. Leave analytics disabled unless you supply one and both analytics secret ARNs.

The reference realm also does not define organization claim mappings. Its demo login can verify OIDC, but project access still needs a supported claim from the IdP and the bootstrap mapping above.

Operate the deployment#

Upgrade or roll back#

Keep the previous bundle, manifest, and configuration. Back up the database under your recovery policy and check migration compatibility before upgrading. Obtain the new bundle and matching manifest, unpack them in a new directory, and run its deploy command with your configuration. Repeat the health, sign-in, and runtime checks above.

To roll application tasks back, run from the retained prior bundle with its manifest:

./bin/cpki-ecs rollback \
  --config "$CPKI_CONFIG" \
  --manifest ./release-manifest.json

Rollback registers the prior task definitions, updates services, and verifies their release. It does not reverse database migrations. The ECS deployment circuit breaker also rolls back failed service deployments; it does not reverse migrations or foundation changes.

Rotate secrets or change capacity#

After changing a secret value, start a new deployment for every service that consumes it. For example, after rotating an app API secret:

aws ecs update-service \
  --region "$AWS_REGION" \
  --cluster "$CPKI_DEPLOYMENT_NAME" \
  --service "${CPKI_DEPLOYMENT_NAME}-app-api" \
  --force-new-deployment

Running tasks do not receive new environment-secret values until they restart. To change service counts, validate an updated configuration and run deploy with the same manifest. API, frontend, and realtime use CPU target tracking through targetCpuUtilization.

Inspect a failed rollout#

Use ECS service events, stopped-task reasons, and /ecs/<deploymentName>/... CloudWatch log groups. Container Insights defaults to enabled. otlpEndpoint passes exporter configuration to instrumented workloads; the bundle does not install an observability backend.

Remove the deployment#

Remove application DNS records first. From the bundle directory, delete the three Intelligence stacks:

./bin/cpki-ecs teardown \
  --config "$CPKI_CONFIG" \
  --confirm "$CPKI_DEPLOYMENT_NAME"

The confirmation must exactly match deploymentName. This disables ALB deletion protection and deletes services, release, and foundation in that order. CloudWatch log groups remain. Customer-managed databases, Redis, VPC, IdP, secrets, certificate, and KMS keys remain.

For the reference environment, follow the bundle README's full teardown order: application DNS, bundle stacks, Keycloak, secrets, then substrate. cpki-ecs teardown alone does not remove those additional stacks.

Implementation references#

The release bundle's README.md, config/example.parameters.json, and bin/cpki-ecs configure --help travel with the version you deploy. For source review, the CLI and configuration validators and CloudFormation templates require Intelligence repository access.