{"id":50369518,"url":"https://github.com/go-to-k/cdk-local","last_synced_at":"2026-06-05T08:00:54.074Z","repository":{"id":360644718,"uuid":"1251047402","full_name":"go-to-k/cdk-local","owner":"go-to-k","description":"Run your CDK-built app locally, no deploy needed — standalone, or kept local while it reaches the real AWS resources and data it depends on, with no `.env` or local copies to maintain.","archived":false,"fork":false,"pushed_at":"2026-06-01T11:59:14.000Z","size":5380,"stargazers_count":6,"open_issues_count":9,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-02T09:24:40.420Z","etag":null,"topics":["aws","aws-cdk","aws-cloudformation","aws-sam","awscdk","awssam","cdk","cloudformation","sam"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/go-to-k.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-27T07:42:09.000Z","updated_at":"2026-06-02T07:29:00.000Z","dependencies_parsed_at":null,"dependency_job_id":"5fb904d6-9d6e-4177-b99c-933b4b9995d4","html_url":"https://github.com/go-to-k/cdk-local","commit_stats":null,"previous_names":["go-to-k/cdk-local"],"tags_count":110,"template":false,"template_full_name":null,"purl":"pkg:github/go-to-k/cdk-local","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-to-k%2Fcdk-local","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-to-k%2Fcdk-local/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-to-k%2Fcdk-local/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-to-k%2Fcdk-local/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/go-to-k","download_url":"https://codeload.github.com/go-to-k/cdk-local/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-to-k%2Fcdk-local/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33935514,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-05T02:00:06.157Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","aws-cdk","aws-cloudformation","aws-sam","awscdk","awssam","cdk","cloudformation","sam"],"created_at":"2026-05-30T06:04:35.773Z","updated_at":"2026-06-05T08:00:53.967Z","avatar_url":"https://github.com/go-to-k.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cdk-local\n\n[![npm version](https://img.shields.io/npm/v/cdk-local.svg)](https://www.npmjs.com/package/cdk-local)\n[![CI](https://github.com/go-to-k/cdk-local/actions/workflows/ci.yml/badge.svg)](https://github.com/go-to-k/cdk-local/actions/workflows/ci.yml)\n[![License: Apache-2.0](https://img.shields.io/npm/l/cdk-local.svg)](./LICENSE)\n\n**Run your CDK app locally — no SAM template, no AWS account. Or bind to your deployed stack and hit its real data.**\nA CDK-native alternative to `sam local`, covering Lambda, API Gateway, ECS, ALB-fronted services, and Bedrock AgentCore.\n\n![cdkl start-api serving a local CDK app's HTTP API; curl in the right pane reaches the local Lambda](assets/cdkl-start-api.gif)\n\n## Quick start\n\nRequires **Docker** (running) and **Node.js 20+**.\n\n```bash\nnpm install -g cdk-local      # installs the `cdkl` command\ncd your-cdk-app               # the directory holding cdk.json\ncdkl invoke                   # pick a Lambda from the list, then run it locally\n```\n\n`cdkl` synths your CDK app and runs the selected resource locally in Docker — a Lambda in its real `public.ecr.aws/lambda/*` container (via the Lambda Runtime Interface Emulator), an ECS task / service as a real container, an API on a local HTTP server. Run any command with no target and it opens an arrow-key picker, so you rarely type a CDK path.\n\n**Bind to your real deployed stack** by adding `--from-cfn-stack`: cdk-local reads the deployed CloudFormation stack and injects its real ARNs, Secret values, and IAM credentials into the container, so your local handler reads and writes the exact same data the deployed app does — no `.env` to wire up, no test data to seed.\n\n```bash\ncdkl start-api --from-cfn-stack            # a local API on real AWS data + real Cognito JWT\ncdkl invoke MyStack/Fn --from-cfn-stack    # one Lambda against real DynamoDB / S3 / Secrets\n```\n\n## Why cdk-local\n\n- **Zero-friction local execution** — no AWS account, no IAM access, no deploy; just Docker and your CDK app. Onboard new engineers, review a PR by actually running its code, or work on an OSS CDK sample without owning the maintainer's account.\n- **Iterate against your real deployed stack — including its data.** `--from-cfn-stack` keeps you on the real DynamoDB rows, S3 objects, Cognito users, and Secret values your IAM credentials reach, instead of paying to seed and anonymize a local emulator.\n- **Picks up where `sam local` leaves off:**\n  - **CDK-native** — point at `cdk.json`; no SAM template to maintain.\n  - **Wider coverage** — Lambda, API Gateway, ECS run-task / service / ALB front-door, and Bedrock AgentCore.\n  - **Real container images** — the Lambda RIE base image; ECS as real Docker. The only dependency is Docker itself.\n\n## What runs locally\n\ncdk-local runs your **application compute** in Docker, using your CDK app as the source of truth. It deliberately does NOT emulate AWS managed services: your code reaches DynamoDB / S3 / Secrets Manager / Cognito / SNS / SQS / etc. as **real AWS** through your IAM credentials (`--assume-role`, or `--from-cfn-stack` to bind to a deployed stack). Want those offline too? Pair cdk-local with a service emulator like LocalStack — it does not bundle one.\n\nThe locally executable resources are listed under [Supported resources](#supported-resources).\n\n## Commands\n\nRun any command with no target for an arrow-key picker (`invoke` / `run-task` pick one; `start-service` / `start-alb` / `start-api` multi-select). Or name a target — the CDK display path (recommended) or a stack-qualified logical ID (`MyStack:Fn1234ABCD`, the SAM-compatible form); single-stack apps may drop the stack prefix.\n\n```bash\ncdkl invoke MyStack/Fn --event ./event.json   # Lambda (ZIP / container image / Function URL)\ncdkl run-task MyStack/Task                     # ECS task, run once\ncdkl start-service MyStack/Worker              # ECS service replicas (no load balancer)\ncdkl start-alb MyStack/WebAlb                  # ECS behind an ALB (front-door per listener)\ncdkl start-api MyStack/Api                     # API Gateway REST v1 / HTTP v2 / WebSocket + Function URLs\ncdkl invoke-agentcore MyStack/Agent            # Bedrock AgentCore Runtime (one POST /invocations)\ncdkl list                                      # every runnable target, grouped by command (alias: ls)\n```\n\n![cdkl invoke against a local sample CDK app — no AWS account, no deploy](assets/cdkl-invoke.gif)\n\n- **`start-api`** serves one HTTP server per API; a bare `start-api` in a multi-stack app needs `--all-stacks` or `--stack \u003cname\u003e`. Add **`--watch`** to re-synth and hot-reload on CDK source changes ([details](docs/local-emulation.md#hot-reload---watch)).\n- **`run-task`** / single-replica **`start-service`** publish declared container ports on the host and log `Reach it at 127.0.0.1:\u003cport\u003e` (`--host-port \u003ccontainer\u003e=\u003chost\u003e` remaps; handy for privileged ports on macOS).\n- **`start-alb`** stands up the ECS service(s) behind an ALB plus a host-side front-door on each listener port, honoring all six listener-rule conditions, weighted forwards, redirect / fixed-response actions, and mixed ECS + Lambda targets ([details](docs/cli-reference.md#cdkl-start-alb-run-an-alb-fronted-service-locally)).\n- **`invoke-agentcore`** invokes a Bedrock AgentCore Runtime agent locally — container or `fromCodeAsset` / `fromS3` managed runtime, HTTP / SSE / WebSocket / MCP protocols, with `customJwtAuthorizer` and `--sigv4` enforcement ([details](docs/cli-reference.md#cdkl-invoke-agentcore-run-bedrock-agentcore-runtime-agents-locally)).\n- Non-TTY (CI / pipes): every command except a bare `start-api` needs an explicit target.\n\nFull flags, precedence, and `--from-cfn-stack` resolution: [docs/cli-reference.md](docs/cli-reference.md) and [docs/local-emulation.md](docs/local-emulation.md).\n\n### start-service vs start-alb — which one?\n\n`start-service` runs just the ECS service's replicas (workers, queue consumers, Service-Connect-only). `start-alb` boots the ECS service(s) behind an ALB **plus** a host-side front-door on each listener port — HTTP and HTTPS (TLS terminated locally with `--tls-cert` / `--tls-key` or an auto-generated self-signed cert) — so external traffic reaches them the way it does in the cloud. Full resolution model: [docs/cli-reference.md](docs/cli-reference.md#cdkl-start-alb-run-an-alb-fronted-service-locally).\n\n## Supported resources\n\n| Resource | Local execution |\n|----------|-----------------|\n| Lambda functions (ZIP, container image, Function URLs) | `invoke` — every current Lambda runtime |\n| API Gateway (REST v1, HTTP v2, WebSocket) + Lambda Function URLs | `start-api` |\n| ECS task definitions | `run-task` |\n| ECS services | `start-service` |\n| Cloud Map / Service Connect registry | service discovery between local replicas |\n| ALB-fronted ECS / Lambda services | `start-alb` — HTTP / HTTPS listeners, all six listener-rule conditions, weighted forwards, redirect / fixed-response, mixed ECS + Lambda targets |\n| Bedrock AgentCore Runtime agents | `invoke-agentcore` — container + `fromCodeAsset` / `fromS3` artifacts, HTTP + MCP |\n\nLambda runs on every current AWS Lambda runtime — Node.js (18/20/22/24), Python (3.11–3.14), Ruby (3.2/3.3), Java (8.al2/11/17/21), .NET (6/8), and the OS-only `provided.al2` / `provided.al2023`. The retired `go1.x` runtime is rejected with a pointer to migrate to `provided.al2023`.\n\n## Programmatic use\n\ncdk-local also exports its commands as Commander factories so a host project can embed it into its own CLI, register custom state sources alongside the built-in `--from-cfn-stack`, and rebrand the embedded commands. See [docs/library-mode.md](docs/library-mode.md) for the API and an example.\n\n## License\n\nApache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgo-to-k%2Fcdk-local","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgo-to-k%2Fcdk-local","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgo-to-k%2Fcdk-local/lists"}