AWS

@ctxpipe/aws-cdk is the AWS self-hosting path for ctx|. It gives you one high-level construct, CtxPipe, that provisions the required infrastructure and wires runtime configuration for you.

Step-by-step deployment flow

1) Install @ctxpipe/aws-cdk in your CDK repo

Use an existing CDK repo, or create a new one first.

Then install:

pnpm add @ctxpipe/aws-cdk aws-cdk-lib constructs

2) Create or reuse a Route 53 hosted zone

You need a hosted zone for your custom domain because the construct configures DNS and TLS from it.

• Reuse an existing public hosted zone if you already manage your domain in Route 53.
• Or create a new hosted zone and delegate your domain/subdomain to it.
• Keep both values ready:
  • customDomain.domainName (example: app.example.com)
  • customDomain.hostedZoneId (example: Z0123456789ABCDEF)

3) Import CtxPipe and configure it

Instantiate the construct in your stack. Follow the same pattern as examples/aws-cdk-self-host.

modelProvider is a union: openai-like (default) or bedrock. Both variants configure tiers through the same models prop (fast required).

OpenAI-compatible provider

import * as cdk from "aws-cdk-lib";
import { CtxPipe } from "@ctxpipe/aws-cdk";

const app = new cdk.App();
const stack = new cdk.Stack(app, "CtxPipeStack");
const modelApiKey = app.node.tryGetContext("modelApiKey");

if (!modelApiKey) {
  throw new Error('Missing CDK context "modelApiKey". Pass -c modelApiKey=...');
}

new CtxPipe(stack, "CtxPipe", {
  orgSlug: "acme",
  size: "medium",
  customDomain: {
    domainName: "app.example.com",
    hostedZoneId: "Z0123456789ABCDEF",
  },
  modelProvider: {
    baseUrl: "https://api.openai.com/v1",
    apiKey: cdk.SecretValue.unsafePlainText(String(modelApiKey)),
    models: {
      fast: "gpt-4.1-mini",
      // Optional: medium, high, embedding
      // medium: "gpt-4.1",
      // high: "gpt-4.1",
    },
  },
});

Amazon Bedrock (task role)

For Bedrock, set kind: "bedrock" and tier model IDs only. The construct grants the backend/worker ECS task roles bedrock:InvokeModel and bedrock:InvokeModelWithResponseStream, injects MODEL_PROVIDER=bedrock and MODEL_BEDROCK_AWS_REGION, and does not create a MODEL_PROVIDER_API_KEY secret. The backend calls Bedrock Runtime with SigV4 credentials from the ECS task role.

Enable each model ID in the Amazon Bedrock console for your stack region before relying on chat or embeddings.

new CtxPipe(stack, "CtxPipe", {
  orgSlug: "acme",
  customDomain: {
    domainName: "app.example.com",
    hostedZoneId: "Z0123456789ABCDEF",
  },
  modelProvider: {
    kind: "bedrock",
    region: "us-east-1", // optional; defaults to stack region
    models: {
      fast: "anthropic.claude-sonnet-4-20250514-v1:0",
      medium: "anthropic.claude-sonnet-4-20250514-v1:0",
      high: "anthropic.claude-opus-4-20250514-v1:0",
      embedding: "cohere.embed-v4:0", // optional; Cohere models only
    },
  },
});

4) Run CDK deploy

OpenAI-like:

cdk synth
cdk deploy -c modelApiKey="$OPENAI_API_KEY"

Bedrock (example context keys from examples/aws-cdk-self-host):

cdk deploy \
  -c modelKind=bedrock \
  -c modelFast="anthropic.claude-sonnet-4-20250514-v1:0" \
  -c orgSlug=acme \
  -c domainName=app.example.com \
  -c hostedZoneId=Z0123456789ABCDEF

5) Wait for deployment and open your custom domain

After cdk deploy completes, open https://<customDomain.domainName>.

6) Complete onboarding with the same orgSlug

When you create the first organization in onboarding, use the exact same slug as the orgSlug you passed to CtxPipe.

Bonus: automate upgrades with CI/CD

Set up CI/CD so dependency upgrades for @ctxpipe/aws-cdk trigger:

1. dependency update (or Renovate/Dependabot PR),
2. cdk synth validation,
3. cdk deploy from your pipeline.

This keeps your self-hosted stack aligned with the construct version you run.

Critical org slug requirement

orgSlug is not only infra config. It must match the org you create in the product onboarding flow.

• The construct configures org-scoped graph runtime values using this slug.
• During first login/onboarding, create the org with the exact same slug.
• If the onboarding org slug does not match the deployed orgSlug, org-scoped graph configuration will not line up as expected.

Why each prop exists

Required props

Optional props

modelProvider union

Optional on both variants: models.medium, models.high, and models.embedding.

Omitted tier IDs cascade: medium → fast, high → medium. The construct maps them to MODEL_FAST_NAME, MODEL_MEDIUM_NAME, MODEL_HIGH_NAME, and MODEL_EMBEDDING_NAME. See Model configuration for what each tier is used for.

For bedrock, modelProviderSecret / modelProviderSecretArn stack outputs are omitted.

Upgrading from older @ctxpipe/aws-cdk versions

Replace defaultModel: "gpt-4.1-mini" with models: { fast: "gpt-4.1-mini" }.

Required nested fields (openai-like)

Required nested fields (bedrock)

High-level architecture

CtxPipe provisions a single AWS stack with these layers:

Only the backend is public. UI and codesearch stay internal and are reached through backend routing.

What this gives you by default

• GRAPH_DB_PROVIDER=neptune and graph URI wiring from Neptune endpoints
• Internal service routing (UI_PROXY_URL, CODESEARCH_URL) so only backend is public
• Generated AUTH_SECRET and managed DATABASE_URL / SMTP secrets
• Public app URL output and secret ARN outputs for operations

How to choose size

Use size to tune compute and database capacity for your single-tenant workload:

• small (default): best for pilot/small-team deployments with moderate repository churn and cost sensitivity. Aurora and Neptune both use db.t4g.medium — AWS’s minimum supported burstable size for these engines (dev/test oriented).
• medium: better for sustained ingestion/reindex workloads where worker and codesearch need more headroom. Aurora uses db.t4g.large; Neptune uses memory-optimized db.r6g.large.
• large: for high-ingestion and lower-latency expectations, with bigger tasks, scaled backend/worker replicas, and db.r6g.xlarge for both Aurora and Neptune.

See the package README sizing table for the full preset matrix.

Signals that you should move up a size:

• ingestion jobs queueing up or taking too long,
• frequent codesearch reindex delays,
• higher p95 response latency during active sync/index windows.

@ctxpipe/aws-cdk keeps services in private subnets for every size. NAT remains required because backend/worker/codesearch need outbound access for model providers, GitHub, and Atlassian APIs.

Related references

• packages/aws-cdk/README.md
• examples/aws-cdk-self-host