local start-api (long-running local API server)

cdkd local start-api stands up a long-running HTTP server that maps synthesized API Gateway routes (REST v1, HTTP API, Function URL) to local Lambda invocations against the AWS Lambda Runtime Interface Emulator. Modeled on sam local start-api but reusing cdkd's synthesis, asset, and route-discovery plumbing — no template.yaml round-trip.

Requires Docker. As with cdkd local invoke, the first run pulls the Lambda base image (~600MB once per machine). Pass --no-pull on subsequent runs to skip the layer check.

cdkd local start-api                              # auto-allocate one port PER discovered API
cdkd local start-api --port 3000                  # first API → 3000, second API → 3001, ...
cdkd local start-api MyAdminApi                   # logical id (single-stack apps)
cdkd local start-api MyStack/MyAdminApi           # OR: CDK Construct path (prefix-matched)
cdkd local start-api --warm                       # pre-start one container per Lambda

One server per API (v0.81+)

Every discovered API surface (AWS::ApiGatewayV2::Api, AWS::ApiGateway::RestApi, AWS::Lambda::Url) gets its own HTTP server on its own port. cdkd prints one Server listening on http://<host>:<port> (<API> (<kind>)) line per server at startup, and one route table per server underneath.

This is a deliberate departure from sam local start-api's single-server-per-template model: realistic CDK apps usually define multiple APIs (admin + public, internal + external) with different authorizer setups, different CORS configs, and overlapping paths. Lumping them into one server forced an awkward "first-match-wins" semantic that didn't mirror AWS Lambda's actual routing. Pre-v0.81 versions did this.

Port assignment:

Pass an optional positional <target> to launch exactly one server for the named API. The same target syntax cdkd local invoke / cdkd local run-task use applies here — the whole cdkd local * family addresses resources consistently:

1. Bare logical id — MyHttpApi. Single-stack apps only; in multi-stack apps cdkd rejects this form with the same disambiguation hint local invoke / local run-task produce. The id is the HTTP API / REST API logical id, or (for Function URLs) the backing Lambda's logical id.
2. Stack-qualified logical id — MyStack:MyHttpApi. Works in any app size; required when the same bare id exists in two stacks.
3. CDK Construct path / display path — MyStack/MyHttpApi/Resource. Exact match against the resource's aws:cdk:path metadata.
4. CDK Construct path prefix — MyStack/MyHttpApi. Matches when the input is a strict ancestor of the resource's aws:cdk:path (same prefix rule cdkd orphan uses): CDK's new apigw2.HttpApi(stack, 'MyHttpApi') synthesizes the L1 child at MyStack/MyHttpApi/Resource, so cdkd local start-api MyStack/MyHttpApi resolves cleanly without having to type the synthesized /Resource suffix.

For Function URLs, the path forms reference the backing Lambda's aws:cdk:path, not the auto-generated URL resource — so cdkd local start-api MyStack/MyHandler matches the Function URL declared by new lambda.Function(this, 'MyHandler').addFunctionUrl().

Routes from templates without aws:cdk:path metadata (hand-rolled cfn.Resource defs, or older CDK that didn't emit the metadata) still match by bare logical id (form 1) and by stack-qualified logical id (form 2) — only the path forms (3, 4) need the metadata.

Deprecated --api <id> alias. Earlier versions used a --api flag for the same purpose. The flag is still accepted in this release (emitting a deprecation warn on use) and accepts the same four forms; it will be removed in a future major release. Migrate scripts / CI to the positional form. Passing both positional and --api at once produces an error — they're mutually exclusive.

Discovered routes

Per-route classification (boot never aborts on per-integration unsupportedness):

The deferred-error class lets you run the supported subset of an API locally even when the CDK app contains direct AWS-service integrations, WebSocket routes, or other unimplemented shapes — only the unsupported routes themselves return 501; everything else dispatches as normal.

REST v1 non-AWS_PROXY integrations

cdkd local start-api emulates all four non-AWS_PROXY REST v1 integration types end-to-end:

The VTL engine at src/local/vtl-engine.ts implements a hand-rolled minimal subset of AWS API Gateway's VTL spec. Supported features:

• Variable references: $var, ${var}, $obj.field.subField
• Built-ins:
  • $input.body — raw request body
  • $input.json('$.path') — JSON-stringified slice (primitives JSON-quoted)
  • $input.path('$.path') — native value
  • $input.params() — {header, querystring, path} union
  • $input.params('name') — path > query > header precedence
  • $input.params('header').<name> / .querystring / .path
  • $context.requestId / httpMethod / resourcePath / stage
  • $context.identity.sourceIp / userAgent
  • $util.escapeJavaScript(s) / base64Encode / base64Decode / urlEncode / urlDecode / parseJson
• Directives: #set($var = expr), #if(cond) / #elseif / #else / #end, #foreach($x in $list) / #end, ## line comments
• Operators: &&, ||, !, ==, !=, <, <=, >, >=
• JSONPath subset: $, $.field, $.field.sub, $.array[index], quoted-string bracket keys

Intentionally NOT supported (any usage surfaces VtlEvaluationError with the offending construct named in the message — converted to HTTP 502 + reason JSON body at request time):

• Velocity arithmetic operators (+ - * /) outside literal concat
• User-defined #macro
• #parse / #include
• Range operator ([1..5])
• $velocityCount and other Velocity context built-ins
• JSONPath filter expressions ($..items, $.items[?(@.x > 5)])

Routing precedence

3 tiers per AWS docs: full match → greedy {proxy+} → $default. Within "full match" tier, more literal segments win as a best-effort tie-break (AWS does not formally specify multi-route precedence within the same tier; cdkd uses literal-segment count as a heuristic).

Flags

Hot reload (--watch)

When --watch is set, cdkd installs a chokidar-backed file watcher over the CDK app's source tree (the synth working directory, where cdk.json lives), excluding cdk.out / node_modules / .git and honoring cdk.json's watch.include / watch.exclude (mirroring cdk watch). A source edit triggers a debounced (500ms window) reload:

1. Re-run cdk synth (skipped when -a <dir> was passed at server boot — the directory is treated as already-synthesized).
2. Re-run route discovery, stage resolution, and CORS-config extraction.
3. Build per-Lambda specs + a fresh container pool.
4. Atomically swap the server state. Routes added / removed / changed take effect on the next request.
5. Dispose the previous pool in the background — in-flight requests complete against the old containers; new requests hit the new pool.

Synth failures during reload do NOT crash the server. The previous version keeps serving and the CLI emits a [warn] line naming the failure. Reloads serialize, so a burst of file changes coalesces to one synth.

CORS preflight

cdkd's HTTP server intercepts OPTIONS preflight requests for HTTP API v2 routes whose AWS::ApiGatewayV2::Api has a CorsConfiguration:

• Match Origin against AllowOrigins (literal entries or *).
• Match Access-Control-Request-Method against AllowMethods.
• Match each Access-Control-Request-Headers entry against AllowHeaders (case-insensitive).
• Respond 204 No Content with the canonical Access-Control-Allow-* headers, plus Access-Control-Max-Age / Access-Control-Expose-Headers / Access-Control-Allow-Credentials when configured.
• Always set Vary: Origin so downstream caches (browser / CDN) do not share the response across origins (load-bearing whenever Access-Control-Allow-Origin was derived from the request — the wildcard echo, literal-origin echo, and AllowCredentials echo paths all qualify).

When AllowCredentials: true AND the origin matched via *, the response echoes the request's literal Origin (browser fetch spec disallows * + credentials).

Access-Control-Request-Headers lists are validated strictly: a malformed entry (e.g. "Content-Type,,Authorization" — a trailing / embedded empty entry) rejects the preflight rather than silently skipping the empty entry. This matches AWS's stricter HTTP API behavior on preflight headers.

When the user has registered an explicit OPTIONS method on a path (an AWS::ApiGatewayV2::Route whose RouteKey is OPTIONS /...) on the same API as the matched route, preflight interception is skipped — the user's Lambda owns the OPTIONS surface. The same-API filter is load-bearing in multi-API stacks: an explicit OPTIONS route on Stack B's REST v1 API at the same path no longer suppresses preflight on Stack A's HTTP API v2.

REST v1 (AWS::ApiGateway::*) CORS via Mock OPTIONS methods IS intercepted when the synthesized template matches CDK's defaultCorsPreflightOptions shape: HttpMethod: 'OPTIONS' + Integration.Type: 'MOCK' + IntegrationResponses[].ResponseParameters carrying literal method.response.header.Access-Control-Allow-* pairs. The headers are extracted at boot (AWS's "'value'" single-quote wrappers are stripped) and the HTTP server returns the captured status and headers directly on OPTIONS requests — no Lambda invocation, no VTL evaluation. The default status code is 204 (matches the CDK default); intrinsic-valued (Fn::Sub / Ref etc.) ResponseParameters are dropped silently because cdkd cannot evaluate VTL locally, and if the drop leaves zero header literals the route falls back to the deferred- error 501 class.

Other REST v1 MOCK shapes (non-OPTIONS methods, MOCK without literal header parameters, MOCK with VTL RequestTemplates that produce custom bodies) are dispatched via the full MOCK handler — see the "REST v1 non-AWS_PROXY integrations" section above.

Stage variables

event.stageVariables is populated from the selected Stage's Variables (REST v1) / StageVariables (HTTP API v2) map.

• Default: the first Stage attached to each API in template order.
• --stage <name>: select a Stage by StageName. Applied per-API — a --stage prod override against an app with three APIs picks the matching Stage on each. APIs without a matching Stage get stageVariables: null and surface a warn line at startup. The resolved stage name is threaded into event.requestContext.stage for both REST v1 and HTTP API v2 routes. AWS supports named stages on HTTP API v2 (CreateStage accepts any name; $default is the auto-deploy default but not the only option), so a v2 template that pins a named Stage gets that name surfaced through the integration event — matching what the deployed endpoint would emit. v2 APIs without a templated Stage continue to use '$default'.
• Function URL routes don't have a Stage — stageVariables stays null regardless of the flag.
• Intrinsic-valued entries (Ref, Fn::GetAtt, Fn::Sub) in the Stage's Variables map are dropped with a warn (mirrors PR 1's env-var policy — the local server has no deploy state to resolve them against).

Container lifecycle

• One pool per Lambda. Each container's RIE port is bound to its own free host port (pickFreePort); the user-facing HTTP server stays on the single --port.
• acquire() returns the first idle container in the pool; lazy-grows up to --per-lambda-concurrency under a per-Lambda mutex. Above the cap, requests queue.
• release() returns the container to the pool and starts a 60s idle timer. Idle GC fires after 60s of inactivity per pool.
• Containers are named cdkd-local-<logicalId>-<pid>-<rand> so an external sweep can mop up orphans (docker ps --filter name=cdkd-local-).

Lambda Layers in local start-api

cdkd local start-api resolves same-stack AWS::Lambda::LayerVersion references the same way cdkd local invoke does — see the Lambda Layers section under local invoke above for the full rules (supported reference shapes, last-layer-wins on file collision, the single merged /opt bind mount, hard-error cases). The merge happens once per Lambda at server boot (not per request); the merged tmpdir is removed by the graceful shutdown path. Single-layer Lambdas skip the copy and bind-mount the layer's asset dir directly.

Container Lambdas (Code.ImageUri) in local start-api

cdkd local start-api supports lambda.DockerImageFunction / Code.ImageUri on the same terms as cdkd local invoke (see the Container Lambdas section under local invoke above). At server boot — and on every --watch reload — cdkd resolves each container Lambda's image once: local-build from the cdk.out asset manifest when the synthesizer produced a matching dockerImages entry (then docker build runs against the recorded build context), or ECR-pull fallback when no asset matches (same-account / same-region only, cross-account / cross-region deferred to a follow-up). The resulting deterministic cdkd-local-invoke-<hash> tag goes into the warm container pool; the pool runs docker run against it verbatim — no /var/task bind-mount, no base-image pull, ImageConfig.Command / ImageConfig.EntryPoint / ImageConfig.WorkingDirectory / --platform (from Architectures) all threaded through. Container Lambdas silently ignore Properties.Layers (matches AWS's invoke-time behavior — layers are baked into the image at build time on the IMAGE branch). Hot reload (--watch) detects Dockerfile / build-context changes via the content-addressed image tag: a real source edit flips the tag at the next reload's docker build, the spec signature compares unequal, and the pool entry tears down + restarts so the next request sees the new image.

Graceful shutdown

SIGINT / SIGTERM / uncaughtException / unhandledRejection all run the same dispose path: drain in-flight requests, tear down every container (tolerating per-container removal failures — logged at warn, loop continues). The verify-time docker ps --filter sweep is the defense-in-depth backstop.

Double-^C bypasses dispose and exits immediately so the user can escape a hung Docker daemon. The skipped containers are reported with the docker ps cleanup command in the warning.

local start-api exit codes

• 0 — server started cleanly and shut down on SIGTERM.
• 1 — startup failure (Docker missing, port bind failed, route discovery rejected) OR uncaught exception during the run.
• 130 — exited via SIGINT.

local start-api authorizers

cdkd supports four authorizer kinds in front of any discovered route:

• Lambda TOKEN (REST v1) — AWS::ApiGateway::Authorizer.Type: 'TOKEN'. The header named in IdentitySource (default method.request.header.Authorization) is forwarded to the authorizer Lambda as event.authorizationToken. The Lambda's response must carry a policyDocument with at least one { Effect: 'Allow', Resource: <methodArn> } statement; cdkd matches Resource against the request's methodArn (literal or */? wildcard) on every request — cached verdicts get re-evaluated against the new methodArn so a narrow-Resource Allow doesn't leak across routes. Allow → context flat under event.requestContext.authorizer. Policy-deny → HTTP 403, missing identity header → HTTP 401 without invoking the Lambda.
• Lambda REQUEST — REST v1 (Type: 'REQUEST') and HTTP v2 (AuthorizerType: 'REQUEST'). The full request snapshot (headers, query string, path parameters) is passed to the authorizer Lambda. HTTP v2 also accepts the simple { isAuthorized, context } response shape in addition to the IAM-policy shape. REST v1 missing-identity → HTTP 401 without invoking the Lambda; HTTP v2 falls through.
• Cognito User Pool (REST v1) — Type: 'COGNITO_USER_POOLS'. The Bearer token from Authorization: Bearer <token> is verified locally against the user pool's published JWKS. Allow → claims under event.requestContext.authorizer.claims. Deny → HTTP 403.
• JWT (HTTP v2) — AuthorizerType: 'JWT'. Same JWKS-based verification, with aud / client_id matched against the JwtConfiguration.Audience allowlist. Allow → claims under event.requestContext.authorizer.jwt.claims. Deny → HTTP 401.

Authorizer results are cached per (authorizer, identity) for the TTL declared by the authorizer (REST v1: AuthorizerResultTtlInSeconds, default 300s, max 3600s; HTTP v2: 0 by default = no cache; JWT: cached for min(remaining-exp, 300s)).

JWKS-fetch failure → pass-through. When the JWKS endpoint is unreachable at startup, cdkd warns and falls back to a pass-through mode where every Bearer token is accepted as if valid (including malformed / non-JWT garbage — a real JWT still gets its claims surfaced into event.requestContext.authorizer, a malformed token gets a synthetic unknown principal and an empty claims map):

[warn] [cognito-jwt] JWKS unreachable at https://cognito-idp.us-east-1.amazonaws.com/us-east-1_xyz/.well-known/jwks.json: ...
        JWT validation will allow all tokens — local dev fallback. Configure
        network access to the JWKS URL to enable real signature verification.

The failure entry has a short TTL (~60s) so a transient blip doesn't lock pass-through for the full 1hr success TTL — the next minute's request retries the JWKS fetch. The pass-through warn line itself fires at most once per JWKS URL per server lifecycle (the warn-set is constructed once at server startup, not per request).

This is a deliberate dev-tool tradeoff: surprising deny is worse than warn+allow when the developer is iterating on a function and the JWKS URL is blocked by a corporate proxy. Do NOT rely on this in any shared environment — the dev's machine accepts every token, including forged ones.

AWS_IAM authorization is supported with signature-verification-only semantics on BOTH REST v1 (AuthorizationType: 'AWS_IAM') and Function URLs (AuthType: 'AWS_IAM') — see the next section. mTLS authorizers and any non-TOKEN/REQUEST/COGNITO_USER_POOLS Type / non-REQUEST/JWT AuthorizerType still hard-error at discovery with the offending route's location named.

local start-api AWS_IAM authorizer (REST v1 + Function URL, signature verification only)

Routes that declare REST v1 AuthorizationType: 'AWS_IAM' OR Function URL AuthType: 'AWS_IAM' boot and serve requests; cdkd verifies the inbound Authorization: AWS4-HMAC-SHA256 ... SigV4 signature against the developer's local AWS credentials (the same default credential chain every other cdkd command uses):

1. Parse the header into (Credential, SignedHeaders, Signature).
2. Reconstruct the canonical request per the AWS SigV4 spec.
3. Derive the signing key from the local secret access key + the request's date / region / service scope.
4. Constant-time compare the recomputed signature with the header's.

Outcomes:

• Valid signature with the dev's credentials → request reaches the handler.
  • REST v1: the handler sees the access-key-id as event.requestContext.authorizer.principalId (flat v1 overlay).
  • Function URL: NO authorizer block is synthesized. The base v2 event's requestContext.authorizer stays null. AWS-deployed Function URLs write principal context under event.requestContext.authorizer.iam.{accessKey, accountId, callerId, userArn, ...}, and cdkd has no local IAM data plane to populate that block (no STS GetCallerIdentity per request, no policy emulation). Emitting principalId under .lambda would mislead handlers that defensive-read .iam, so the deployed and local behavior diverge only by absence of identity context — never by location.
• No / malformed Authorization header, signature mismatch under the dev's own credentials, or any other rejection → 403 matching the deployed response:
  • REST v1: 403 ({"message":"Missing Authentication Token"}) for missing-identity, 403 ({"message":"Forbidden"}) for policy-deny — matches AWS-deployed API Gateway REST v1 IAM rejection (lowercase message).
  • Function URL: 403 ({"Message":"Forbidden"}) for both deny kinds — matches Lambda's deployed Function URL IAM rejection (capital Message).
• Different Credential access-key-id than the dev has → warn-and-pass. The local server cannot reproduce a signing key it doesn't have, and refusing every foreign-identity request would defeat the dev-tool purpose. The warn fires at most once per foreign access-key-id per server lifecycle.

Pass --strict-sigv4 to opt IN to fail-closed mode — every unverifiable signature (foreign access-key-id, missing local AWS credentials, etc.) is denied with the same 403 the deployed API Gateway would return. Use this when you want local parity with the deployed signature-enforcement boundary. The default (warn-and-pass) matches cdk-local's cdkl start-api.

What is NOT verified locally (deliberately out of scope):

• IAM resource / action / condition policy evaluation. The local server has no IAM data plane. Signature-verified callers reach the handler under their own identity; downstream authorization is the dev's responsibility. Use the deployed API to test the full IAM policy surface.
• STS temporary credentials' session-token validation against AWS. We accept whatever session-token the request was signed with.

At startup cdkd emits a one-line warn naming every IAM-protected route so the developer is aware of the signature-verification-only boundary:

[warn] 2 route(s) declare AuthorizationType: AWS_IAM — cdkd local start-api
       verifies SigV4 signatures against your local AWS credentials, but does NOT
       emulate IAM policy evaluation (resource / action / condition rules).
       Signature-verified callers reach the handler under their own identity;
       downstream authorization is the dev's responsibility.
[warn]   - MyStack/ProtectedMethod
[warn]   - MyStack/AnotherProtectedMethod

Tooling that signs requests works out of the box — common helpers include aws-sigv4-sdk (AWS SDK v3 signer), curl --aws-sigv4, Postman's AWS Signature auth, and the awscurl CLI.

local start-api VPC-config Lambdas

Lambdas with Properties.VpcConfig set still run locally — cdkd does NOT block these — but the local container does NOT get attached to the deployed VPC's subnets. Calls from the handler to private RDS / ElastiCache / VPC-only endpoints will fail. cdkd surfaces a one-line warn at startup naming each affected Lambda:

[warn] Lambda MyVpcLambda has VpcConfig — local container will reach external
        services via the host's network, NOT through the deployed VPC's
        NAT/private subnets. Calls to private RDS/ElastiCache will fail.

AWS SDK calls from the container still use the developer's shell credentials (or --assume-role-issued temp creds) and reach the public AWS endpoints; nothing about that path changes.

local start-api mTLS (mutual TLS)

cdkd local start-api supports API Gateway custom-domain mutual TLS: when all three --mtls-truststore <path> / --mtls-cert <path> / --mtls-key <path> flags are set, the server switches from plain HTTP to HTTPS and the TLS handshake itself enforces the client-certificate trust check against the supplied CA bundle. Clients without a cert, with a self-signed cert, or with a cert that doesn't chain to one of the CAs in the trust store are rejected by Node's tls module BEFORE the request reaches cdkd's per-request handler — no per-request code path is needed.

The verified client certificate is surfaced on the Lambda event under:

• REST v1: event.requestContext.identity.clientCert
• HTTP API v2: event.requestContext.authentication.clientCert

Both shapes match AWS API Gateway's deployed-mTLS event shape:

{
  "clientCertPem": "-----BEGIN CERTIFICATE-----\n...",
  "subjectDN": "CN=client,O=example,C=US",
  "issuerDN": "CN=My CA,O=example,C=US",
  "serialNumber": "01:23:45:...",
  "validity": {
    "notBefore": "May 22 03:30:00 2026 GMT",
    "notAfter": "May 22 03:30:00 2027 GMT"
  }
}

mTLS runs ORTHOGONALLY to the existing TOKEN / REQUEST / COGNITO_USER_POOLS / JWT authorizers — the TLS handshake completes first (rejecting unknown-CA clients), then the authorizer pipeline runs against the already-authenticated client.

Partial flag sets are rejected at CLI parse time (the server never boots in a half-configured state): if any of the three flags is set, all three must be set. Leave all three unset for plain HTTP (the pre-PR default).

Generating a local CA + server + client cert with openssl

# 1. Create a local CA
openssl req -x509 -newkey rsa:2048 -nodes \
  -keyout ca-key.pem -out ca.pem \
  -subj "/CN=cdkd-local-ca" -days 365

# 2. Generate a server cert signed by the local CA
openssl req -newkey rsa:2048 -nodes \
  -keyout server-key.pem -out server-csr.pem \
  -subj "/CN=localhost"
openssl x509 -req -in server-csr.pem \
  -CA ca.pem -CAkey ca-key.pem -CAcreateserial \
  -out server-cert.pem -days 365

# 3. Generate a client cert signed by the local CA
openssl req -newkey rsa:2048 -nodes \
  -keyout client-key.pem -out client-csr.pem \
  -subj "/CN=client"
openssl x509 -req -in client-csr.pem \
  -CA ca.pem -CAkey ca-key.pem -CAcreateserial \
  -out client-cert.pem -days 365

# 4. Start the server with mTLS enabled
cdkd local start-api \
  --mtls-truststore ca.pem \
  --mtls-cert server-cert.pem \
  --mtls-key server-key.pem

# 5. curl the server with the client cert
curl --cacert ca.pem \
  --cert client-cert.pem --key client-key.pem \
  https://localhost:<port>/items

mTLS scope

• The mTLS configuration is at the SERVER level (the equivalent of an API Gateway custom-domain MutualTlsAuthentication.TruststoreUri). cdkd does NOT parse the synth template's AWS::ApiGateway::DomainName / AWS::ApiGatewayV2::DomainName resources — the CLI flags are the authoritative source. If your CDK app declares mTLS on a DomainName, you can re-use the same CA bundle locally by pointing --mtls-truststore at the file you uploaded to the deployed truststore S3 location.
• The server cert and key are for the LOCAL server only (clients connect to localhost). Self-signed is the typical case.
• AWS-deployed mTLS uses MutualTlsAuthentication.TruststoreVersion for live trust-store updates; the local server reads the --mtls-truststore file once at boot. Restart cdkd local start-api to pick up a new CA bundle (the --watch reload pipeline does NOT re-read the mTLS materials).

local start-api v1 scope (out of scope, deferred)