FREE TOOL

AgentCore Dockerfile Checker

Paste a Dockerfile and check it against the Amazon Bedrock AgentCore Runtime container contract: ARM64, 0.0.0.0 on port 8080, 8000 or 9000 per protocol, a numeric USER and the 53-layer limit.

HTTP :8080 MCP :8000 A2A :9000 AG-UI :8080

The container contract →What a Dockerfile cannot show →USER and the 53-layer limit →

See the check ↓

FAILListens on 127.0.0.1

uvicorn listens on 127.0.0.1, so only the container itself reaches it: AgentCore's requests never arrive, and invocations end in a 504 or a RuntimeClientError.

--host 0.0.0.0

CHECKPlatform left to the build

The Dockerfile does not fix the platform, so the image gets the build machine's - amd64 on most laptops and CI runners. Build with --platform linux/arm64, or pin it in FROM.

docker buildx build --platform linux/arm64 -t IMAGE --load .

CHECKUSER agent

A non-numeric USER fails the container's start once the image has more than 53 layers (424, "Failed to mount overlay"). This Dockerfile adds 4 layers to the base image's - use the numeric UID (id agent inside the container prints it) and the count stops mattering.

USER 1000

OKPort 8080

uvicorn listens where AgentCore sends HTTP requests.

OKEXPOSE 8080

The image documents the port AgentCore uses.

YOUR CODE MUST SERVE, ON HTTP PORT 8080POST /invocations, GET /ping, /ws for WebSocket

TRY IT LOCALLY

docker buildx build --platform linux/arm64 -t agent:arm64 --load .
docker run --rm --platform linux/arm64 -p 8080:8080 agent:arm64
curl http://localhost:8080/ping

Building container images and deploying them to AWS are AWS Developer Associate topicsTry free DVA-C02 practice questions with answers and explanations.DVA-C02 questions →

The AgentCore Runtime container contract

AgentCore Runtime runs your image in a microVM of its own for each session and sends the requests to a port and paths set by the protocol the runtime is created with. Whatever the protocol, the image must be ARM64 and the server must listen on 0.0.0.0:

Protocol	Port	Paths
HTTP	8080	POST /invocations, GET /ping, /ws for WebSocket
MCP	8000	POST /mcp (streamable HTTP)
A2A	9000	POST /, GET /.well-known/agent-card.json, GET /ping
AG-UI	8080	POST /invocations (SSE), /ws, GET /ping

An MCP server must use the streamable HTTP transport; AWS recommends stateless mode (stateless_http=True), in which the server must accept the Mcp-Session-Id header the platform adds. An A2A server must also serve its agent card at /.well-known/agent-card.json.

A server on 127.0.0.1 - uvicorn's, gunicorn's and flask run's default - or on another port gets no requests: invocations end in a 504 Gateway Timeout or a RuntimeClientError, and an image built for amd64 fails with exec format error. The AgentCore Error Decoder reads those errors.

What a Dockerfile cannot show

/ping. It answers {"status": "Healthy"}, or HealthyBusy while background work runs - a session reporting HealthyBusy is kept alive. Set time_of_last_update only when the status changes, or leave it out: a timestamp that moves on every ping keeps idle sessions alive until their maximum lifetime and uses up the session quota. The AgentCore SDK answers /ping for you.
The image's size. An AgentCore Runtime takes a Docker image of up to 2 GB, a limit that cannot be raised. docker image inspect IMAGE --format "{{.Size}}" prints it in bytes.
The registry. The runtime's containerUri must point to Amazon ECR - push the image there first.
MMDSv2. Since June 30, 2026 a runtime must have requireMMDSV2 set to true in its metadataConfiguration, or its invocations fail with This runtime is not MMDSv2-enabled. It is the runtime's setting, not the image's: aws bedrock-agentcore-control get-agent-runtime --agent-runtime-id AGENT_ID --query metadataConfiguration.
The session's hardware. A session gets at most 2 vCPU and 8 GB of memory, which cannot be raised.

USER and the 53-layer limit

A container whose image has more than 53 layers and a non-numeric USER directive - such as USER agent rather than USER 1000 - fails to start: InvokeAgentRuntime returns 424 Failed Dependency, and the runtime's log says Failed to mount overlay: No such file or directory. The base image's layers count too, so the checker cannot know the total; it counts the layers your Dockerfile adds (one per RUN, COPY and ADD). The numeric UID avoids the problem whatever the count - id agent inside the container prints it. To count the built image's layers: docker inspect IMAGE | jq '.[0].RootFS.Layers | length'.

AWS also recommends running the container as a non-root user, so an image without USER gets a warning too.

Frequently asked questions

Is my Dockerfile sent anywhere?

No. It is read in your browser: nothing you paste is uploaded, processed on a server or stored. The page only counts that the checker was used, with which protocol and which first finding, never the file.

How do I build an ARM64 image on an x86 machine?

With Docker Buildx: docker buildx build --platform linux/arm64 -t IMAGE --load . builds it locally, and with --push instead of --load it goes straight to ECR. Or build in AWS CodeBuild on ARM. Pinning FROM --platform=linux/arm64 in the Dockerfile makes a plain docker build produce ARM64 too.

The checker says "address set in your code" - what do I check?

The command starts a program, not a server the checker knows, so the address is in your code - for example uvicorn.run(app, host="0.0.0.0", port=8080) as in AWS's example, or FastMCP(host="0.0.0.0", stateless_http=True) for an MCP server. Run the image locally and call it on the protocol's port, as the commands under the check do.

Do I need a Dockerfile at all?

No. AgentCore Runtime also takes direct code deployment: a ZIP package of up to 250 MB (750 MB unzipped), which is what the AgentCore CLI's agentcore deploy uploads in AWS's MCP example. The Dockerfile matters when you bring your own container image.

Should the Dockerfile contain AWS credentials?

No. In AgentCore Runtime the AWS SDKs get the runtime's execution role credentials from the microVM's metadata service. Access keys in ENV or ARG end up in the image, and the SDKs would use them instead of the role. The Credentials Chain Troubleshooter shows the order in which the SDKs look for credentials.

References

Understand the AgentCore Runtime service contract
HTTP protocol contract
MCP protocol contract
Troubleshoot AgentCore Runtime
Get started without the AgentCore CLI
Security best practices for AgentCore Runtime
Quotas for Amazon Bedrock AgentCore