# How to exec into an ECS container

How-to guides · Updated 16 November 2026

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

## Prerequisites checklist

| Requirement | Detail |
|---|---|
| Exec enabled on the task | Set on the service or `run-task`. Only tasks started *after* enabling it have the agent, hence the forced deployment. |
| Task role permissions | The **task role** (not the execution role) needs `ssmmessages:CreateControlChannel`, `CreateDataChannel`, `OpenControlChannel` and `OpenDataChannel` |
| Network path | The task must reach the Systems Manager messages endpoint: via a NAT gateway, a public IP, or an `ssmmessages` interface VPC endpoint |
| Your machine | AWS CLI v2 and the Session Manager plugin |
| Your permissions | `ecs:ExecuteCommand` on the cluster or task |
| The image | Has 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

| Error | Fix |
|---|---|
| `TargetNotConnectedException` | Agent can't reach SSM: task role permissions or networking. See [the TargetNotConnected guide](https://cloudconsole.dev/errors/ecs-execute-command-targetnotconnected). |
| "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 |
| `AccessDeniedException` | Your identity lacks `ecs:ExecuteCommand`, or a condition in your policy (such as a cluster tag) doesn't match |
| Session opens then closes immediately | The 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](https://cloudconsole.dev/cli/ecs-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.

## 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 CloudConsole app](https://cloudconsole.dev/aws-console-app) · [Download on the App Store](https://apps.apple.com/app/cloudconsole-for-aws/id6835419710)

## Sources

- [Monitor Amazon ECS containers with ECS Exec](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-exec.html)
- [ExecuteCommand API reference](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ExecuteCommand.html)

## Related

- [aws ecs execute-command](https://cloudconsole.dev/cli/ecs-execute-command)
- [ECS Exec: TargetNotConnectedException when calling the ExecuteCommand operation](https://cloudconsole.dev/errors/ecs-execute-command-targetnotconnected)
- [aws ecs describe-tasks](https://cloudconsole.dev/cli/ecs-describe-tasks)
- [How to connect to EC2 with Session Manager](https://cloudconsole.dev/how-to/connect-to-ec2-with-session-manager)
- [aws ecs update-service](https://cloudconsole.dev/cli/ecs-update-service)
- [How to add my IP to an AWS security group](https://cloudconsole.dev/how-to/add-my-ip-to-security-group)

---

Source: https://cloudconsole.dev/how-to/ecs-exec-into-container

CloudConsole is an independent iPhone and Android app for Amazon Web Services by Cloudconcur Ltd. It is not affiliated with Amazon Web Services.
