Prerequisites

Before you begin, install and verify the following tools.

Local development

To run AIDLC Collaborative locally, install the following tools.

Run the following commands to verify your local development environment.

node --version   # Expected output: v22.x 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.

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.

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"

You must also have an AWS account with permissions to manage the following services.

Optional tools

The following are optional. Set them up to enable additional features.

Agent authentication

Agents authenticate using API keys configured through the platform UI. The platform supports two options:

An agent CLI cannot reach its model until an effective credential is configured — the Bedrock AgentCore runtime has no IAM-role fallback. A user can provide a personal credential in Account Settings, a space owner/admin can provide a shared credential in Space Settings → Agent, or a platform admin can provide a fallback in Admin → Agents. 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 (required for Claude Code, OpenCode, and Codex setups)

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: the Bedrock AgentCore runtime's IAM role intentionally has no Amazon Bedrock model-invocation permissions, so there is no IAM-role fallback. Agents authenticate to Bedrock exclusively through this token.

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

Where these values are stored

All credentials 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 do not use ambient AWS credentials; they use the effective Kiro or Bedrock key selected through the hierarchy above.

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.

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.