Skip to content
Skip to content
Documentation

Deploy ASH on AWS

The repository's deploy/ directory has infrastructure as code for running ASH as a service in your own AWS account: an MCP server for agents, a pull request gate, and a sharded pipeline for large repositories. Each target comes as a CDK stack, with its synthesized CloudFormation template committed, and as a Terraform module.

ASH publishes no container image, so every deployment builds the ASH image into an ECR repository in your account, with a CodeBuild project that clones ASH from GitHub and rebuilds the image on a schedule.

What deploy/ provides

Target What it deploys CDK template Terraform module
Image pipeline ECR repositories and scheduled CodeBuild builds of the ASH image AshImagePipeline ash-image-pipeline
AgentCore ASH's MCP server on Amazon Bedrock AgentCore Runtime AshAgentCore agentcore
Fargate ASH's MCP server on ECS Fargate behind an internal Application Load Balancer AshFargate fargate
CodeCommit gate A container Lambda function that scans a CodeCommit pull request and comments on it AshCodeCommitGate codecommit-gate
Distributed pipeline A CodePipeline that splits one scan across CodeBuild shards and merges the results into one verdict AshDistributedPipeline codepipeline-executor
  • deploy/cdk is a CDK app in TypeScript. Its templates are in deploy/cdk/templates, and you can launch them from the CloudFormation console without running CDK. Each target template includes its own image build.
  • deploy/terraform has one module per target. Every target module uses the image that the ash-image-pipeline module builds, and you start its first build yourself after terraform apply.
  • deploy/cdk-constructs has ASHScanStep, a construct that adds an ASH scan to a CDK Pipelines pipeline. It is not published to npm or any other registry; you build it from the repository to use it.

deploy/README.md lists the parameters the targets share and how the CDK and Terraform names map.

Prerequisites:

  • An AWS account, and credentials that can create IAM roles, an ECR repository, a privileged CodeBuild project (it builds a container image), and the services of the target you choose.
  • Outbound internet access for the image build. CodeBuild clones ASH from GitHub, pulls the Python base image from Amazon ECR Public, and downloads the scanner tools.
  • For a console launch, nothing else. To deploy from source, Node.js and npm for CDK, or Terraform with access to the Terraform registry for terraform init.

Before you deploy

  • AshVersion, the git ref the image is built from, defaults in the CloudFormation templates to the ASH release they ship in. The Terraform ash_version variable has no default, and the Terraform examples pin the same release. Both accept a tag, a branch, or a full commit SHA. The targets need options that no release up to 3.7.1 has: stateless MCP (ash mcp --stateless-http), and ash merge with the shard options for the distributed pipeline. Set AshVersion to an ASH that has them, for example the commit SHA you deploy from. With one that lacks them, the Fargate MCP container exits at startup, the AgentCore server starts in stateful mode and logs a warning, and the distributed pipeline cannot run its shard and merge commands. Each target's README lists what it needs.
  • The image is only as current as its last build. The build runs on the RebuildSchedule you set, and rebuilding the image does not update a running service on its own; each target's README says how to roll it out.
  • Deleting a stack leaves the ECR repository and artifact buckets in place on purpose.
  • The image the targets build has neither bubblewrap nor firejail. When a client's config or a scanned repository's config sets sandbox.mode to bwrap or firejail, every scanner that mode would wrap is MISSING and the scan is incomplete: an MCP scan ends with status incomplete, and ash exits with code 1.

Network defaults

The CloudFormation templates set these defaults. The Terraform modules have defaults of their own: for example, the fargate module can terminate TLS with a certificate and lets its tasks send to any address. Each module's README lists them, and each README explains how to change them.

  • Fargate: the load balancer is internal, listens on HTTP port 80, and has no ingress rule until you set McpIngressCidr, which rejects 0.0.0.0/0. With it empty, nothing can reach the endpoint. The tasks can send only TCP 443.
  • AgentCore: the runtime uses AgentCore's PUBLIC network mode, and callers reach it through the IAM-authorized InvokeAgentRuntime API.
  • Both MCP targets: the server checks a shared header only when you set McpAuthHeaderName and McpAuthHeaderValue. Both are empty by default, which leaves the network rules (and, on AgentCore, IAM) as the only control on who can call it.

Target READMEs

Each module's README covers its inputs, outputs, verified behavior, and known limitations:

For the CDK stacks, see deploy/cdk/README.md. To run ASH's MCP server yourself instead, see Run the MCP server.