AWS Setup
Install the runner on your AWS account by launching our CloudFormation stack — it takes about 5 minutes.
For the high-level picture of how the runner fits into Deployment.io's architecture, see Architecture.
What gets installed in your AWS account
The CloudFormation stack creates the resources below. All resources are tagged created by: deployment.io so you can audit and clean up after.
Compute
- ECS cluster (
dr-linuxamd-{orgID}) with a Fargate capacity provider plus an EC2 capacity provider. - AWS controller — a small ECS task on Fargate (0.25 vCPU, 0.5 GB) that runs continuously. Polls Deployment.io for jobs and dispatches them.
- Runner — an ECS task on EC2 m6a.large (6 GB) that scales from zero. Only runs when there's a deployment or Task to execute. Mounts the host's Docker socket so it can build images.
- Auto Scaling Group backing the EC2 capacity (
min: 0,max: 2). - EC2 Launch Template that defines the EC2 instance for the ASG.
- Your services, sites and previews run in a separate cluster,
ecs-{orgID}, in a VPC namedvpc-{orgID}. The runner creates both on the first deploy; they aren't part of the stack.
IAM (five roles)
- Lambda role — used only during stack creation by the bootstrap Lambda. Can create the ECS service-linked role and the task-execution role.
- ECS Instance role — attached managed policy
AmazonEC2ContainerServiceforEC2Role, lets the EC2 host register with ECS. - Task Execution role (
eTERole-…) — created by the bootstrap Lambda. HasAmazonECSTaskExecutionRolePolicy,CloudWatchFullAccess, andSecretsManagerReadWrite. - Task Role (
dr-task-role-…) — runtime role assumed by the runner container. Hasiam:PutRolePolicy / GetRolePolicy / GetRole / PassRoleonrole/*,iam:CreateServiceLinkedRolefor ECS, ELB, and RDS service-linked roles, andsts:AssumeRoleon the Bedrock role. The runner uses this role to provision the AWS resources your deployments need. - Bedrock role (
dr-bedrock-…) — can only invoke Amazon Bedrock models. The runner assumes it to hand short-lived Bedrock credentials to the agent; see AWS Bedrock.
Networking
- The runner EC2 instance lives in the subnet you select during installation. Outbound only; whether it gets a public IP follows the subnet's auto-assign setting.
- The Fargate AWS controller runs in the same subnet with
AssignPublicIp: ENABLEDso it can reachgo.deployment.io:443. The runner images are pulled from Docker Hub, and the bootstrap Lambda callsapi.deployment.ioonce during installation.
Other
- Bootstrap Lambda (Python 3.12, 100s timeout) — runs once on stack create to set up the ECS service-linked role. Does nothing after.
- CloudWatch log groups:
dr-logs-group-…(runner output) anddr-aws-controller-logs-group-…(controller output). Created when the controller and the runner first write logs; the controller starts at install.
Install steps
1. Open the runner setup
In the dashboard, go to Org Settings → Agents → Runners and click the
Add runner button. (The same install flow is also available inline
from the environment creation page if you're already there.)
-
Launch CloudFormation stack
Select the region where you want to install the runner and launch the CloudFormation stack.
-
Select the subnet where you want to install the runner
Sign in to your AWS account. On the CloudFormation stack creation page, select the subnet on which you want to install the runner. Then clickCreate stackto start the installation.

- Check the installation logs
Watch the CloudFormation event logs to confirm the runner installed without errors. We don't have visibility into AWS-side errors during installation, so the AWS console is the source of truth here.

Cost on your AWS bill
- Idle baseline (~$8/mo): the always-on Fargate AWS controller (0.25 vCPU + 0.5 GB) plus negligible CloudWatch logs.
- Active runtime: the EC2 m6a.large adds ~$0.09/hr while a job is running, then scales back to zero. So 1 active hr/day adds ~$3/mo; 8 active hrs/day adds ~$20/mo.
- Tasks impact: Task agent runs are typically longer than deployment jobs (multi-step agent sessions, often 10–30 min). A team running ~20 Tasks/day on top of regular deployments will see EC2 hours accumulate faster.
In practice, the runner itself lands between $10 and $40/month for most teams. Heavier Task workloads can push higher — monitor the ECS cluster's compute time in CloudWatch if you want a precise number.
What your deployments add
These come from what you deploy, not from the runner:
- Network (~$35/month): the first web service, private service or database you deploy creates a network in your account, once per runner. Its NAT gateway costs about $35/month in AWS for as long as it exists, plus a small charge per GB of traffic through it — even when nothing is running.
- Load balancer (~$20–30/month each): every web service gets its own Application Load Balancer.
- Public IPv4 addresses (~$3.60/month each): AWS charges for every public IPv4 address — the NAT gateway's, and the load balancer's in each availability zone.
- The services themselves: Fargate compute for each running service, and RDS for each database (Deploy AWS RDS), at AWS's prices for the CPU, memory and storage you choose.
Static sites need none of the first three: they run on S3 and CloudFront, billed by storage and traffic.
Uninstalling
- First delete your services, static sites and databases in the dashboard, while the runner is still installed. That removes what each one created: load balancers, ECR repositories, CloudFront distributions, S3 buckets and RDS databases.
- Then delete the CloudFormation stack from the AWS console (or
aws cloudformation delete-stack). It removes the resources the stack created: thedr-linuxamd-{orgID}cluster, the Auto Scaling Group, the Launch Template, the Lambda and the stack's IAM roles. - A few things outlive the stack. Delete them in the AWS console if you're removing Deployment.io completely:
- the
ecs-{orgID}cluster and thevpc-{orgID}VPC, including its NAT gateway, which costs about $35/month in AWS even when nothing runs; - the
eTERole-…IAM role, which the bootstrap Lambda created; - the log groups
dr-logs-group-…,dr-aws-controller-logs-group-…and{orgID}/….
- the
Email us at hello@deployment.io if there's any installation error or you have other questions.