local start-agentcore (serve a Bedrock AgentCore Runtime locally)

cdkd local start-agentcore [target] is the long-running serve counterpart of the single-shot local invoke-agentcore. It boots the AgentCore Runtime container once (same image / env / credential resolution as invoke-agentcore) and keeps it warm, serving the runtime's native protocol contract so a client can hit it repeatedly:

• HTTP / AGUI runtimes serve POST /invocations + GET /ping (proxied to the warm container, with the session-id / boot-resolved Authorization injected and the request/response — including an SSE stream — piped through) and the bidirectional /ws WebSocket endpoint behind a host bridge that injects the AgentCore session-id (and, under a customJwtAuthorizer, the Authorization header) on the container upgrade — so a header-less client (e.g. a browser WebSocket, which cannot set custom upgrade headers) can hold an interactive multi-frame session. Both share the same host port; the ready banner prints both an HTTP contract served on http://... line and the Server listening on ws://... line.
• MCP runtimes serve POST /mcp; A2A runtimes serve POST / (these have no /ws bridge, and print a Server listening on http://... ready line plus a <PROTOCOL> contract served on http://... line).

Runs until ^C. Models cdk-local's cdkl start-agentcore, inherited into cdkd's command tree as a thin pass-through to cdk-local's command factory. Requires Docker.

local start-agentcore target resolution

Same shape as local invoke-agentcore: a CDK display path (MyStack/MyAgent) or stack-qualified logical ID. Single-stack apps may omit the stack prefix. Omit the target in a TTY for an interactive picker over the discovered AgentCore Runtimes.

local start-agentcore state-source flags

start-agentcore is one of the factory pass-throughs that bind deployed state via the extraStateProviders seam: cdk-local's start-agentcore factory accepts it, so cdkd threads its S3-backed --from-state factory in and layers the cdkd-specific --from-state / --state-bucket / --state-prefix flags on top of cdk-local's inherited --from-cfn-stack / --stack-region. Use --from-state (after a prior cdkd deploy) or --from-cfn-stack [name] (for a stack deployed via the upstream CDK CLI) to substitute Ref / Fn::GetAtt / Fn::Sub / Fn::ImportValue / Fn::GetStackOutput intrinsics in the runtime container image + environment variables. Mutually exclusive. (start-alb, start-service, and — as of cdk-local 0.128.0 — start-cloudfront thread --from-state the same way.)

local start-agentcore options

• --port <n> — serve bind port the client connects to (default 0 = OS-assigned). The HTTP contract and the /ws bridge share this one port; the ready banner prints the chosen http://<host>:<port> + ws://<host>:<port>/ws.
• --host <ip> — serve bind host (default 127.0.0.1).
• --session-id <id> — pin one AgentCore session-id for every forwarded request / /ws connection (default: a fresh UUID each, so each is its own session).
• --bearer-token <jwt> — Bearer JWT presented under a customJwtAuthorizer (verified against the runtime's OIDC discovery URL before the container starts, then forwarded on every request and the container /ws upgrade). Now the default-when-missing fallback — the inbound JWT gate is per request, not boot-time (see below).
• --no-verify-auth — skip the inbound JWT verification (a --bearer-token, if given, is still forwarded).
• --sigv4 — sign each forwarded request with AWS SigV4 (service bedrock-agentcore) when the runtime declares no customJwtAuthorizer, so the warm container sees the same Authorization / X-Amz-* headers the cloud receives. Mutually exclusive with --bearer-token; ignored (with a warning) when a customJwtAuthorizer is declared.
• --watch — re-synth + reload the warm container in place on a CDK source change, keeping the host serve up (only the container rotates; a per-firing classifier picks rebuild vs soft-reload, the same machinery as invoke-agentcore --ws --watch). Off by default.
• --env-vars <file> — SAM-shape env-var overrides.
• --platform <linux/amd64|linux/arm64> — defaults to linux/arm64 (AgentCore's required arch).
• --container-host <host> — host to bind the container ports to.
• --timeout <ms> — per-request timeout.
• --from-state / --from-cfn-stack [name] / --state-bucket / --state-prefix / --stack-region — state-source flags (above).
• --assume-role [arn] / --ecr-role-arn <arn> — role-assumption + cross-account ECR image-pull flags.
• --no-pull / --no-build — pull / build skip.

local start-agentcore inbound auth (customJwtAuthorizer)

When the runtime declares an inbound customJwtAuthorizer, the warm serve verifies each contract request's Authorization per request (matching the cloud): 401 when the header is missing, 403 when the token is invalid, forwarded on a pass. GET /ping is unauthenticated. The container boots without requiring a token up front; --bearer-token is the default token used when a request arrives without its own Authorization. For a SigV4-protected runtime (no customJwtAuthorizer) use --sigv4 instead to sign each forwarded request.

local start-agentcore lifecycle

The container is started once and kept warm; HTTP / AGUI contract requests are proxied to it and each /ws client opens its own container upgrade with the session-id (and optional Authorization) injected. ^C (SIGTERM / SIGINT) tears the container down and exits — no cdkd-local-agentcore-* container is left behind. The studio agentcore-ws serve kind (cdk-local) spawns this command, but cdkd does not embed cdk-local's studio command, so that surface is not exposed by the cdkd CLI.