Prerequisites
Before you begin, install and verify the following tools.
Local development
To run AIDLC Collaborative locally, install the following tools.
| Tool | Version | Purpose |
|---|---|---|
| Node.js | 22.22 or later | Runtime for the frontend and Lambda functions |
| npm | 10 or later | Package manager (ships with Node.js) |
| Git | 2.x | Repository cloning and branch management for agent execution |
Run the following commands to verify your local development environment.
node --version # Expected output: v22.22.0 or later
npm --version # Expected output: 10.x or later
git --version # Expected output: 2.x
AWS deployment
To deploy AIDLC Collaborative to AWS, install the following additional tools. For detailed deployment instructions, see Setup.
| Tool | Version | Purpose |
|---|---|---|
| Terraform | 1.4 or later | Infrastructure provisioning |
| AWS Command Line Interface (AWS CLI) | v2 | AWS resource management and credential handling |
| curl | HTTPS support | Authenticated Public ECR base-image manifest preflight |
| Docker (default) | 20.10 or later | Lambda packaging and container builds; alternatives use the override documented below |
Run the following commands to confirm the default Docker-based deployment tools are installed. If you use an alternative container runtime, follow the section below instead of the Docker verification command.
terraform --version # Expected output: v1.4 or later
aws --version # Expected output: aws-cli/2.x
docker --version # Expected output: Docker version 20.10 or later
Using an alternative container runtime
Docker is the default container runtime; no configuration is needed when its standard socket is available. DOCKER_HOST selects the Docker Engine API socket that Terraform's kreuzwerker/docker provider connects to when it builds and pushes the container images. The installer does not invoke or require a container-runtime CLI.
Because the image build talks to the Docker Engine API socket (rather than shelling out to a CLI), any runtime that exposes such a socket works. Point DOCKER_HOST at the runtime's socket and the build behaves exactly as it does with Docker.
| Runtime | Docker API socket | Status |
|---|---|---|
| Docker (default) | standard /var/run/docker.sock |
Supported |
| Podman | derived at runtime (see below) | Verified end-to-end |
| Rancher Desktop (dockerd/moby mode) | ~/.rd/docker.sock |
Verified end-to-end |
| Colima | ~/.colima/default/docker.sock |
Compatible (same mechanism) |
| OrbStack | ~/.orbstack/run/docker.sock |
Compatible (same mechanism) |
Podman example:
# macOS
podman machine start
export DOCKER_HOST="unix://$(podman machine inspect --format '{{.ConnectionInfo.PodmanSocket.Path}}')"
# Rootless Linux (after starting `podman system service`)
export DOCKER_HOST="unix://$(podman info --format '{{.Host.RemoteSocket.Path}}')"
Rancher Desktop example (set the container engine to dockerd (moby) in Rancher Desktop settings):
export DOCKER_HOST="unix://$HOME/.rd/docker.sock"
Finch and CLI-only build tools are not supported
Finch does not expose a Docker Engine API socket by default, so there is no socket for DOCKER_HOST to use and the Terraform image build cannot run. The same applies to daemonless/CLI-only build tools such as Buildah, nerdctl, Kaniko, and BuildKit. Use Docker, Podman, or another socket-based runtime from the table above.
You must also have an AWS account with permissions to manage the following services. Services marked (optional) are only needed when the matching feature is enabled. For the resources created in each service and the services called only at runtime, see AWS services.
| Category | Services |
|---|---|
| Compute | AWS Lambda, Amazon ECS with Fargate (Yjs collaboration server), Application Auto Scaling, Amazon Bedrock AgentCore (agent runtime), AWS CodeBuild (managed environment images) |
| Networking | Amazon VPC, Amazon API Gateway (REST and WebSocket), Amazon CloudFront, Elastic Load Balancing, Amazon Route 53 (optional) |
| Storage | Amazon S3, Amazon DynamoDB, Amazon Neptune |
| Security | Amazon Cognito, AWS Identity and Access Management (IAM), AWS KMS, AWS Secrets Manager, AWS Systems Manager Parameter Store, AWS WAF (optional), AWS Certificate Manager (optional) |
| Integration | Amazon Elastic Container Registry (Amazon ECR), Amazon EventBridge, Amazon SQS, AWS Cloud Control API (AgentCore deployment) |
| Observability | Amazon CloudWatch (Logs and alarms) |
At runtime the application also calls Amazon Inspector (managed environment image scan results), the AWS Price List API (Bedrock cost estimates), and Amazon Bedrock (model discovery and invocation). CodeCommit is optional for spaces using it as their code host. If service control policies restrict these calls, permit the Regions actually used:
- Amazon Inspector: the deployment Region.
- AWS Price List:
ap-south-1for deployments inap-*Regions;us-east-1for all other deployments. - Amazon Bedrock: the configured Bedrock Region (
bedrock_region, defaulting to the deployment Region) and, in IAM mode, the inference Region selected for the platform or space connection. Include any destination Regions required by the chosen cross-Region inference profiles. - AWS CodeCommit: the repository's Region, using the external access role described in CodeCommit setup.
Optional tools
The following are optional. Set them up to enable additional features.
| Item | Purpose |
|---|---|
| AWS credentials | Required for large language model (LLM) features through Amazon Bedrock |
| Provider OAuth apps | GitHub / GitLab / Jira Cloud OAuth apps enable code-host and tracker integration — see Setup → Configure provider OAuth apps |
| Custom domain | An ACM certificate in us-east-1 covering the hostname, or a Route53 hosted zone for Terraform to request one — see Setup → Custom domain |
| Enterprise SSO | An OIDC/SAML application in the external IdP and, for OIDC, a Secrets Manager client secret — see Enterprise SSO |
Agent authentication
Agents authenticate using API keys or a dedicated Bedrock IAM inference role configured through the platform UI. Platform administrators select Keys or IAM mode in Admin → Agents → Platform Agent Credentials; Kiro uses its own API key in either mode.
An agent CLI cannot reach its model until an effective credential is configured — the Bedrock AgentCore runtime has no IAM-role fallback. For API keys, a user can provide a personal credential in Account Settings, a Space Owner can provide a shared credential in Space Settings → Agent, or a platform admin can provide a fallback in Admin → Agents. Key resolution is independent per provider and follows personal > space > platform.
Kiro CLI API key (required for the Kiro CLI driver)
Kiro API keys are turned off by default. A Kiro administrator must first enable them in the Kiro console (Settings → Kiro settings → Enable users to generate API keys → On). Users can then sign in to the Kiro portal and generate a key. See the Kiro API keys documentation for details.
Save the key as the Kiro API Key at the intended personal, space, or platform scope. AgentCore resolves the selected opaque binding for each invocation and provides the value to Kiro as KIRO_API_KEY.
Amazon Bedrock API key (Keys mode for Claude Code, OpenCode, and Codex)
Generate an Amazon Bedrock API key in the AWS Console (Amazon Bedrock → API keys → Generate long-term API key, scoped to your account and region). Save it as the Bedrock Bearer Token at the intended personal, space, or platform scope. AgentCore injects the selected value for that invocation as AWS_BEARER_TOKEN_BEDROCK.
This token is required for Claude Code, OpenCode, and Codex agents in Keys mode. The Bedrock AgentCore runtime's IAM role intentionally has no Amazon Bedrock model-invocation permissions, so a missing token does not fall back to that role.
For Codex, additionally enable access to the OpenAI models (openai.gpt-5.*) in the Bedrock console for your Region — Codex uses Bedrock's OpenAI-compatible Responses API, and the models are Region-limited. See Use Codex with Amazon Bedrock. (GPT models are also available through Kiro, but Kiro accesses them via its own API key — no Bedrock model access is involved there.)
Amazon Bedrock IAM (alternative to a Bedrock API key)
In IAM mode, the credential broker assumes a dedicated external inference role and supplies temporary credentials to Claude Code, OpenCode, and Codex. Platform administrators configure a platform connection and optional space overrides; personal Bedrock keys do not apply. The inference account and Region can differ from the deployment. See Bedrock IAM for setup, trust policies, and permissions.
Where API keys are stored
API keys are stored in AWS Systems Manager Parameter Store as SecureString parameters:
- Platform:
/<project_name>/<environment>/<credential-name> - Space:
/<project_name>/<environment>/projects/<project-id>/agent-credentials/<credential-name> - Personal:
/<project_name>/<environment>/users/<user-id>/agent-credentials/<credential-name>
The credential name is bedrock-bearer-token or kiro-api-key. An unset platform credential holds the literal value placeholder, which the platform treats as "not configured"; clearing a space or personal credential deletes that scoped parameter so resolution can fall through.
AWS credentials for deployment
AIDLC Collaborative infrastructure still requires valid AWS credentials for deployment and AWS resource management. Agent CLI model calls use the effective Kiro or Bedrock key, or the temporary inference-role credentials in IAM mode.
Without an effective agent credential, users can still browse the application and edit draft intents, but credential-backed AI composition, Quorum assists, and intent start are unavailable.
Public ECR permissions for container builds
The deployment identity needs the following additional permissions to pull the pinned AgentCore and Yjs base images with authentication. Private ECR push permissions alone do not grant Public ECR access. Add these statements to the deployment policy; runtime application roles do not need them:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ecr-public:GetAuthorizationToken",
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "sts:GetServiceBearerToken",
"Resource": "*",
"Condition": {
"StringEquals": {
"sts:AWSServiceName": "ecr-public.amazonaws.com"
}
}
}
]
}
Public ECR authentication uses us-east-1, including when deploying the
application in another Region. Region restrictions in deployment policies or
organization policies must permit this token request. Tokens last 12 hours.
See AWS's authentication guide
and GetAuthorizationToken permissions.
Automatic Public ECR authentication applies to the updated deployment script and reusable deployment workflow. Managed installations of older tagged releases still use their bundled deployment scripts and do not receive this authentication automatically. On paths using this authentication, a failure stops deployment before apply or retired-task changes. Keep BuildKit enabled: the locked provider's legacy builder does not forward this auth session.
KMS permissions for infrastructure encryption
The example tfvars leaves kms_key_arn empty. DynamoDB remains encrypted at rest with the AWS-owned key, and the deployment principal does not need KMS administration permissions.
To use a customer-managed key for DynamoDB, supply its full key ARN in kms_key_arn. The key must be managed outside this Terraform stack. Its key policy must enable IAM authorization for the deployment account (or directly authorize the principals below); an explicit service-principal grant to DynamoDB alone is not sufficient.
The deployment principal needs kms:DescribeKey, kms:Encrypt, kms:Decrypt, kms:ReEncrypt*, kms:GenerateDataKey*, and kms:CreateGrant on the key so Terraform can enable encryption and DynamoDB can establish its resource grants. Application roles receive the same key-scoped permissions from this stack only through DynamoDB (kms:ViaService), with kms:CreateGrant additionally restricted by kms:GrantIsForAWSResource. For a cross-account key policy that does not delegate to account IAM, directly authorize both the deployment principal and the generated application role ARNs.