# ECS, Fargate and Cloud Run

URL: https://shellz.dev/docs/install/ecs-cloud-run

> Record ECS Exec sessions on ECS and Fargate, and run shellz in Cloud Run and other managed container platforms.

On ECS (including Fargate) and Cloud Run, shellz runs inside your containers. Each task or instance joins a fleet. shellz detects the platform on its own and reports task and container details to the dashboard.

## Before you start

1. [Create a fleet](https://shellz.dev/docs/install/container-image.md#1-create-a-fleet) with the platform **ECS / Fargate** or **Cloud Run**, and copy its token.
2. [Add shellz to your image](https://shellz.dev/docs/install/container-image.md#2-add-shellz-to-the-image).

## ECS and Fargate

### 1. Store the token in Secrets Manager

```bash
aws secretsmanager create-secret --name shellz-fleet-token --secret-string szf_<fleet token>
```

The task execution role needs `secretsmanager:GetSecretValue` on this secret.

### 2. Update the task definition

```json title="task-definition.json"
{
  "containerDefinitions": [
    {
      "name": "app",
      "image": "123456789012.dkr.ecr.eu-west-1.amazonaws.com/app:1.4",
      "entryPoint": ["/usr/local/bin/shellz", "run", "--"],
      "command": ["/app/server", "--port", "8080"],
      "stopTimeout": 30,
      "secrets": [
        { "name": "SHELLZ_FLEET_TOKEN", "valueFrom": "arn:aws:secretsmanager:eu-west-1:123456789012:secret:shellz-fleet-token" }
      ]
    }
  ]
}
```

- `stopTimeout: 30` gives shellz time to finish uploading recordings (up to 20 seconds) before the container is killed.
- shellz reads the task, container name and image from the ECS task metadata endpoint, so you don't need to set them.

> [!IMPORTANT]
> ECS can only inject secrets as environment variables, and anyone with ECS Exec access to the task can read those. Either limit `ecs:ExecuteCommand` to the people who should have it, or have an init container write the secret to a shared volume mounted at `/run/secrets/shellz-fleet-token` and drop the `secrets` entry.

### 3. Test with ECS Exec

```bash
aws ecs execute-command --cluster prod --task <task id> --container app --interactive --command "/bin/bash"
```

ECS Exec sessions are recorded like any other exec. The fleet page lists each task as a member.

### ECS on EC2

If you run ECS on EC2 instances you manage, you can install shellz on the instances instead, with the [Docker host](https://shellz.dev/docs/install/docker-host.md) install. That records every exec into every container on the instance without changing images, and records logins to the instance itself.

## Cloud Run

Cloud Run has no built-in exec command. If you open shells in Cloud Run containers through other tooling, shellz records them like any other exec. Add shellz to the image, then mount the token from Secret Manager as a file:

```bash
printf '%s' 'szf_<fleet token>' | gcloud secrets create shellz-fleet-token --data-file=-
gcloud run deploy app \
  --image=europe-docker.pkg.dev/acme/app/app:1.4 \
  --set-secrets=/run/secrets/shellz-fleet-token=shellz-fleet-token:latest
```

The member is named after the Cloud Run service.

## Other platforms

Nomad, Fly.io, Railway, Render and similar platforms work the same way: add shellz to the image, make `shellz run --` the entrypoint and give the container the token as a file at `/run/secrets/shellz-fleet-token` or as `SHELLZ_FLEET_TOKEN`. Set `SHELLZ_CONTAINER_NAME` and `SHELLZ_IMAGE` to label members, and give the container a stop timeout of 30 seconds or more. See [Container settings](https://shellz.dev/docs/reference/container-settings.md).