AWS Marketplace Deployment

Deploy TeamLoop as a self-hosted instance in your own AWS account. Your data never leaves your VPC.

What You Get

The CloudFormation stack creates a production-ready environment:

VPC with 2 availability zones, public and private subnets, NAT gateway
Aurora PostgreSQL Serverless v2 with pgvector, encrypted at rest, 7-day backup retention
AWS Cognito User Pool with email-based auth (federable with your corporate SAML IdP)
ECS Fargate service running API and Dashboard containers (non-root, auto-scaling 1—4 tasks)
Application Load Balancer with optional HTTPS via ACM certificate
Secrets Manager for database credentials and integration token encryption key
IAM roles scoped to Bedrock (Titan embeddings + reranking) and Marketplace metering
Database migration Lambda that enables pgvector, pgcrypto, and pg_trgm extensions on first deploy

Prerequisites

An AWS account with permission to create CloudFormation stacks, VPCs, ECS services, RDS clusters, and IAM roles
An active TeamLoop subscription on AWS Marketplace
Optional: An ACM certificate ARN if you want a custom domain with HTTPS
Optional: A SAML IdP metadata URL if you want SSO federation via Cognito

Deployment Steps

Find TeamLoop on AWS Marketplace and subscribe. You will receive the container image URIs needed for the next step.

2. Launch the CloudFormation Stack

Navigate to CloudFormation > Create Stack in the AWS Console and upload the TeamLoop template. You can also launch directly from the Marketplace listing.

3. Configure Stack Parameters

Parameter	Default	Description
`VpcCidr`	`10.0.0.0/16`	CIDR block for the new VPC
`ApiImageUri`	(required)	ECR image URI for the API container
`DashboardImageUri`	(required)	ECR image URI for the Dashboard container
`DomainName`	(empty)	Custom domain (e.g., `teamloop.example.com`)
`CertificateArn`	(empty)	ACM certificate ARN (required if DomainName is set)
`AuroraMinCapacity`	`0.5`	Minimum Aurora Serverless v2 ACU (0.5—128)
`AuroraMaxCapacity`	`4`	Maximum Aurora Serverless v2 ACU (1—128)
`VoyageApiKey`	(empty)	Optional Voyage AI key (uses Titan V2 if empty)
`EnableSamlFederation`	`false`	Enable SAML IdP on the Cognito User Pool
`SamlMetadataUrl`	(empty)	Your SAML IdP metadata URL

4. Wait for Stack Creation

Stack creation takes approximately 15 minutes. The migration Lambda runs automatically to enable PostgreSQL extensions, then the ECS service starts.

5. Access TeamLoop

Once the stack status is CREATE_COMPLETE, find the application URL in the Outputs tab:

TeamLoopURL — Your custom domain (if configured) or the ALB DNS name
CognitoUserPoolId — Needed for admin user creation
CognitoHostedUIDomain — Cognito login page URL

Post-Deployment

Create Your First Admin User

Open the Cognito console and navigate to the User Pool created by the stack
Click Create user and enter an email address
The user receives a temporary password via email
Sign in at the TeamLoop URL and set a permanent password

Connect Integrations

Integration setup is the same as the SaaS version. In the TeamLoop dashboard:

Go to Settings > Integrations
Enter API tokens for GitHub, Notion, or Linear
Tokens are encrypted at rest using the auto-generated encryption key in Secrets Manager

Configure SAML Federation (Optional)

If you set EnableSamlFederation to true during stack creation:

The stack creates a SAML identity provider in Cognito using your metadata URL
Users from your corporate IdP can sign in via the Cognito hosted UI
Attribute mapping is pre-configured for email and name claims

To add SAML after initial deployment, update the stack with EnableSamlFederation set to true and provide the SamlMetadataUrl.

Custom Domain with Route 53 (Optional)

Create a CNAME record pointing your domain to the ALB DNS name (from stack outputs)
Ensure your ACM certificate covers the domain and was provided as CertificateArn
The stack automatically configures HTTPS with TLS 1.3

Configuration

Embeddings

Option	When
Amazon Titan V2 (default)	No `VoyageApiKey` provided. Uses Bedrock — no external API calls leave your account.
Voyage AI (BYOK)	Provide your `VoyageApiKey`. Best quality for technical content.

The embedding model is locked per organization after the first embedding is generated. You cannot mix models.

Authentication

Cognito is configured with:

Email-based sign-in with strong password policy (12+ chars, mixed case, numbers, symbols)
Two app clients: one for the Dashboard (PKCE flow) and one for MCP CLI (localhost callback)
Optional SAML federation for corporate SSO

Connecting MCP Clients

Marketplace deployments use OAuth 2.0 with Cognito instead of API keys. Users authenticate through the Cognito hosted UI — the same credentials they use for the dashboard. If SAML federation is enabled, corporate SSO works automatically.

Your MCP endpoint URL is https://YOUR_DOMAIN/mcp/ (or the ALB DNS name from the ALBURL stack output if no custom domain is configured).

For per-client setup instructions (Cursor, Claude Code, VS Code, and others), see MCP Setup — AWS Marketplace.

Database

Aurora PostgreSQL Serverless v2 with:

Automatic scaling between your configured ACU min/max
Encrypted storage, CloudWatch log exports
Snapshot-on-delete protection
Automatic credential rotation support via Secrets Manager

Auto-Scaling

ECS tasks scale between 1 and 4 based on CPU utilization (target: 70%). Scale-out cooldown is 60 seconds; scale-in cooldown is 300 seconds.

Differences from SaaS

Aspect	SaaS	Marketplace
Auth	Auth0	AWS Cognito
Database	Neon	Aurora PostgreSQL Serverless v2
Embeddings	Voyage AI	Amazon Titan V2 (or BYOK Voyage)
Hosting	TeamLoop-managed	Your AWS account
Data residency	TeamLoop infrastructure	Your VPC
Scaling	Managed	Configurable (Aurora ACU, ECS tasks)

Billing

Usage is metered through AWS Marketplace:

Queries — per-query metering
Entities — hourly gauge of stored entities

All charges appear on your standard AWS bill.

Troubleshooting

Stack creation fails

Check the Events tab in CloudFormation for the first FAILED resource
Common cause: insufficient IAM permissions. Ensure your role can create VPCs, RDS clusters, ECS services, IAM roles, and Lambda functions
Aurora creation can fail if the selected region does not support Serverless v2. Verify region support

Cannot access TeamLoop after deployment

Confirm the ECS service has at least one running task in the ECS console
Check the ALB target group health checks — both API (port 8080) and Dashboard (port 80) must be healthy
Review container logs in CloudWatch under /ecs/<stack-name>/api and /ecs/<stack-name>/dashboard

Cognito federation not working

Verify the SAML metadata URL is accessible from the internet
Check that attribute mapping matches your IdP’s claim names
Confirm EnableSamlFederation is true in the stack parameters

Database connectivity issues

The Aurora cluster is in private subnets and only accepts connections from ECS tasks and the migration Lambda
Check that the security groups allow traffic on port 5432
Verify the migration Lambda completed successfully (check its CloudWatch log group)

Next Steps

MCP Setup — Configure your AI assistant to connect to your Marketplace instance
Integrations — Connect GitHub, Notion, and Linear
Query Playground — Explore temporal query modes