parlel/ecs

A zero-dependency, in-process fake of AWS ECS (Elastic Container Service). Speaks the AWS JSON 1.1 wire protocol, so the real @aws-sdk/client-ecs works against it unchanged.


Port	`4703`
Protocol	AWS JSON 1.1 (`X-Amz-Target: AmazonEC2ContainerServiceV20141113.<Op>`)
Health	`GET /_parlel/health`
Reset	`POST /_parlel/reset`

Default connection

AWS_ENDPOINT_URL=http://127.0.0.1:4703
AWS_ACCESS_KEY_ID=parlel
AWS_SECRET_ACCESS_KEY=parlel
AWS_REGION=us-east-1

Any SigV4 credentials are accepted (auth is not verified).

Supported operations

Category	Operations
Clusters	`CreateCluster`, `ListClusters`, `DescribeClusters`, `DeleteCluster`
Task definitions	`RegisterTaskDefinition`, `ListTaskDefinitions`
Tasks	`RunTask`, `ListTasks`, `DescribeTasks`, `StopTask`
Services	`CreateService`, `ListServices`, `DescribeServices`, `UpdateService`, `DeleteService`

SDK usage example

import { ECSClient, CreateClusterCommand, RegisterTaskDefinitionCommand, RunTaskCommand } from "@aws-sdk/client-ecs";

const ecs = new ECSClient({
  endpoint: "http://127.0.0.1:4703",
  region: "us-east-1",
  credentials: { accessKeyId: "parlel", secretAccessKey: "parlel" },
});

await ecs.send(new CreateClusterCommand({ clusterName: "prod" }));
await ecs.send(new RegisterTaskDefinitionCommand({
  family: "web",
  containerDefinitions: [{ name: "nginx", image: "nginx:latest" }],
}));
const run = await ecs.send(new RunTaskCommand({ cluster: "prod", taskDefinition: "web", count: 2 }));
console.log(run.tasks.map((t) => t.lastStatus)); // ["RUNNING", "RUNNING"]

Access via MCP / preview URL

When running inside a Daytona sandbox, this HTTP service is exposed at an automatically-provisioned preview URL. Point the SDK endpoint at that URL and add the x-daytona-preview-token header on requests.

Surface coverage

This emulator faithfully replicates the API surface most application code and agents exercise. Anything below the supported lines is either an intentional design choice for a fast, zero-cost local emulator (✓ By design) or a candidate for a future release (⟳ Roadmap) — never a silent inaccuracy.

Legend: ✅ fully supported · ◐ accepted (stored, not strictly enforced) · ✓ by design · ⟳ on the roadmap.

Area	Limitation
Scheduling	Tasks go straight to `RUNNING`; there is no real placement or container runtime.
Services	`runningCount` always equals `desiredCount`; no rolling deployments or health checks.
Container instances	EC2 container instances / capacity providers are not modeled.
Networking	`awsvpc` ENI attachments are not created.
Auth	SigV4 is accepted but never validated.
Persistence	In-memory; lost on restart/reset.

Configuration — `test.env`

Copy these into your test.env (used by the bridge sidecar flow). Tokens are Parlel's seeded test credentials — any non-empty value is accepted by the emulator, so you rarely need to change them. Swap in real credentials only when pointing at the live service in prod.env.

AWS_ACCESS_KEY_ID=parlel
AWS_SECRET_ACCESS_KEY=parlel
AWS_REGION=us-east-1
AWS_ENDPOINT_URL=http://parlel-bridge:4703