Local ECS for integration tests

Run local Amazon ECS for tests with fakecloud. Full 76-operation API, real Fargate-style task execution via Docker, rolling + CODE_DEPLOY blue/green deployments, daemons, ECS Exec. Free, AGPL-3.0.

Need local ECS for integration tests? Use fakecloud.

curl -fsSL https://fakecloud.dev/install.sh | bash
fakecloud

Point your AWS SDK at http://localhost:4566. Tasks really run — RunTask shells out to docker pull + docker run, captures the exit code, and forwards stdout/stderr to fakecloud CloudWatch Logs when the container declares logDriver=awslogs.

Why fakecloud for ECS

Smoke test (5 commands)

# Start fakecloud.
fakecloud &

# Create a cluster + register a task definition.
aws --endpoint-url http://localhost:4566 ecs create-cluster --cluster-name demo
aws --endpoint-url http://localhost:4566 ecs register-task-definition \
  --family hello \
  --container-definitions '[{"name":"app","image":"busybox:latest","essential":true,"command":["echo","hello from ecs"]}]'

# Run it. The container actually executes.
aws --endpoint-url http://localhost:4566 ecs run-task --cluster demo --task-definition hello

# Inspect captured output.
curl http://localhost:4566/_fakecloud/ecs/tasks

Assert on what was run (first-party SDKs)

import { FakeCloud } from "fakecloud";

const fc = new FakeCloud();
const { tasks } = await fc.ecs.getTasks({ cluster: "demo" });
const { logs, exitCode } = await fc.ecs.getTaskLogs(tasks[0].taskArn);

expect(exitCode).toBe(0);
expect(logs).toContain("hello from ecs");

Same API in Python, Go, Java, PHP, and Rust. See the SDKs page for per-language examples.

What about LocalStack?

LocalStack's ECS support is paid-only since the March 2026 Community switch. fakecloud is free, AGPL-3.0, and ships the full 60-operation API plus real container execution.

Running inside Kubernetes

Running fakecloud itself inside Kubernetes? Set FAKECLOUD_ECS_BACKEND=k8s (or the global FAKECLOUD_CONTAINER_BACKEND=k8s) and ECS tasks run as native Pods instead of Docker containers — no docker-in-docker. See the Kubernetes backend guide.

Read the docs