CloudConsole

How to exec into an ECS container

Updated 16 November 2026 · How we write and check guides

Short answer

Turn on ECS Exec for the service (aws ecs update-service --enable-execute-command --force-new-deployment), make sure the task role allows the ssmmessages actions and the Session Manager plugin is installed on your machine, then run aws ecs execute-command --cluster c --task id --container name --interactive --command "/bin/sh". It works on Fargate and EC2.

Use it safely, in 5 steps: 1. Audit; 2. Least privilege; 3. Don't fix things by hand inside a container; 4. Turn it off; 5.…
The steps from this page at a glance; the console and CLI details are below.

Prerequisites checklist

RequirementDetail
Exec enabled on the taskSet on the service or run-task. Only tasks started after enabling it have the agent, hence the forced deployment.
Task role permissionsThe task role (not the execution role) needs ssmmessages:CreateControlChannel, CreateDataChannel, OpenControlChannel and OpenDataChannel
Network pathThe task must reach the Systems Manager messages endpoint: via a NAT gateway, a public IP, or an ssmmessages interface VPC endpoint
Your machineAWS CLI v2 and the Session Manager plugin
Your permissionsecs:ExecuteCommand on the cluster or task
The imageHas the shell or binary you ask for (/bin/sh exists in most; distroless images have none)

Enable it and connect

# 1. Enable on the service and replace tasks so they pick it up
aws ecs update-service --cluster prod --service orders-api \
  --enable-execute-command --force-new-deployment

# 2. Pick a task and check the agent is running
TASK=$(aws ecs list-tasks --cluster prod --service-name orders-api \
  --query 'taskArns[0]' --output text)
aws ecs describe-tasks --cluster prod --tasks "$TASK" \
  --query 'tasks[0].{exec:enableExecuteCommand,agents:containers[].managedAgents[].[name,lastStatus]}'

# 3. Open a shell
aws ecs execute-command --cluster prod --task "$TASK" \
  --container app --interactive --command "/bin/sh"

The ExecuteCommandAgent should report RUNNING. --container is optional for single-container tasks. You can run a one-off command instead of a shell, for example --command "env", but the session is still interactive.

Fixing the usual errors

ErrorFix
TargetNotConnectedExceptionAgent can't reach SSM: task role permissions or networking. See the TargetNotConnected guide.
"The execute command failed because execute command was not enabled when the task was run"Enable it and force a new deployment
"SessionManagerPlugin is not found"Install the Session Manager plugin locally
AccessDeniedExceptionYour identity lacks ecs:ExecuteCommand, or a condition in your policy (such as a cluster tag) doesn't match
Session opens then closes immediatelyThe command doesn't exist in the image; try /bin/sh instead of /bin/bash

Use it safely

  • Audit: the cluster's execute command configuration can log session output to CloudWatch Logs or S3, and every ExecuteCommand call is in CloudTrail.
  • Least privilege: restrict ecs:ExecuteCommand to specific clusters or container names; production shells should be rare and deliberate.
  • Don't fix things by hand inside a container. Changes vanish when the task is replaced. Use the shell to diagnose, then fix in the image or task definition.
  • Turn it off again (--no-enable-execute-command plus a deployment) if you enabled it only for an investigation.
  • Interactive sessions only: ECS Exec is built for interactive use. For scripted one-off jobs, start a separate task with run-task and a command override.

Questions

Can I exec into a Fargate container?

Yes. ECS Exec works on Fargate as well as EC2, as long as the task was started with execute command enabled and the prerequisites are met.

What is the AWS CLI command to exec into an ECS task?

aws ecs execute-command --cluster my-cluster --task task-id --container app --interactive --command "/bin/sh".

Does ECS Exec need SSH or open ports?

No. It uses an agent and Systems Manager channels, so no inbound ports or SSH keys are needed.

CloudConsole ECS service screen on a phone, for following up on How to exec into an ECS container away from your desk
When this happens away from your desk

Debugging inside a container needs a real terminal. CloudConsole, a phone app for AWS, is built for the step before: seeing task status, stopped reasons and logs on your phone so you know whether to head for a laptop.

About the app → · Download on the App Store

Sources