Image Management·续

Image Management·续

After you configure the registry, use the same fully qualified Docker Hub image reference shown above.

Use private Amazon ECR images

Configure Amazon ECR in Wrangler using these values:

registry domain: <AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com
access key flag: --aws-access-key-id=<AWS_ACCESS_KEY_ID>
secret: matching AWS secret access key

Public ECR images are not supported. To generate the required credentials, create an IAM user with a read-only policy. The following example grants access to all image repositories in AWS account 123456789012 in us-east-1.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": ["ecr:GetAuthorizationToken"],
            "Effect": "Allow",
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "ecr:BatchCheckLayerAvailability",
                "ecr:GetDownloadUrlForLayer",
                "ecr:BatchGetImage"
            ],
            // arn:${Partition}:ecr:${Region}:${Account}:repository/${Repository-name}
            "Resource": [
                "arn:aws:ecr:us-east-1:123456789012:repository/*"
                // "arn:aws:ecr:us-east-1:123456789012:repository/example-repo"
            ]
        }
    ]
}

After you create the IAM user, use its credentials to configure the registry in Wrangler. Wrangler prompts you to create a Secrets Store store if one does not already exist, then stores the secret there.

Interactive:

npmyarnpnpm

npx wrangler containers registries configure <AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com --aws-access-key-id=<AWS_ACCESS_KEY_ID>

yarn wrangler containers registries configure <AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com --aws-access-key-id=<AWS_ACCESS_KEY_ID>

pnpm wrangler containers registries configure <AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com --aws-access-key-id=<AWS_ACCESS_KEY_ID>

CI or scripts:

printf '%s' "$AWS_SECRET_ACCESS_KEY" | npx wrangler containers registries configure <AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com --aws-access-key-id=<AWS_ACCESS_KEY_ID> --secret-name=<SECRET_NAME> --skip-confirmation

After you configure the registry, use the fully qualified Amazon ECR image reference in your Wrangler configuration:

{
    "containers": [
        {
            "image": "<AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com/<REPOSITORY>:<TAG>"
        }
    ]
}

[[containers]]
image = "<AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com/<REPOSITORY>:<TAG>"

Use private Google Artifact Registry images

Configure Google Artifact Registry in Wrangler using these values:

registry domain: <REGION>-docker.pkg.dev
Google service account email flag: --gar-email=<SERVICE_ACCOUNT_EMAIL>
secret: the service account JSON key

The public credential is the service account email, supplied with --gar-email. It must match the client_email field in the service account key.

The private credential is the service account JSON key. Provide it through stdin (a file path, raw JSON, or base64) or the interactive prompt (a file path or base64). Wrangler stores the key base64-encoded in Secrets Store.

Caution

Only *-docker.pkg.dev hosts are supported. Container Registry hosts such as gcr.io and *.gcr.io are not supported, because Google has shut down Container Registry.

To generate the required credentials, create a service account with the Artifact Registry Reader role and download its JSON key:

In the Google Cloud console ↗︎, go to IAM & Admin > Service Accounts.
Select Create service account, then enter a name, ID, and optional description.
Grant the service account the Artifact Registry Reader role, then select Done.
Select the service account, then open the Keys tab.
Select Add key > Create new key, choose JSON, then select Create. The key file downloads to your machine.

Interactive: Wrangler prompts for the key, where you enter a file path or base64-encoded JSON:

npmyarnpnpm

npx wrangler containers registries configure <REGION>-docker.pkg.dev --gar-email=<SERVICE_ACCOUNT_EMAIL>

yarn wrangler containers registries configure <REGION>-docker.pkg.dev --gar-email=<SERVICE_ACCOUNT_EMAIL>

pnpm wrangler containers registries configure <REGION>-docker.pkg.dev --gar-email=<SERVICE_ACCOUNT_EMAIL>

CI or scripts: Pipe the key through stdin (the key contents as raw JSON or base64, or a path to the key file)

cat <PATH_TO_KEY> | npx wrangler containers registries configure <REGION>-docker.pkg.dev --gar-email=<SERVICE_ACCOUNT_EMAIL> --secret-name=<SECRET_NAME> --skip-confirmation

If you have already stored the key in Secrets Store, reference the existing secret and omit the key:

npx wrangler containers registries configure <REGION>-docker.pkg.dev --gar-email=<SERVICE_ACCOUNT_EMAIL> --secret-name=<EXISTING_SECRET_NAME> --skip-confirmation

After you configure the registry, use the fully qualified Google Artifact Registry image reference in your Wrangler configuration:

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "containers": [
    {
      "image": "<REGION>-docker.pkg.dev/<PROJECT_ID>/<REPOSITORY>/<IMAGE>:<TAG>"
    }
  ]
}

[[containers]]
image = "<REGION>-docker.pkg.dev/<PROJECT_ID>/<REPOSITORY>/<IMAGE>:<TAG>"

To use an image from a registry not listed above, push it to the Cloudflare Registry.

Note

With wrangler dev, image references from the Cloudflare Registry, Docker Hub, Amazon ECR, and Google Artifact Registry are supported in local development.

With vite dev, image references from external registries such as Docker Hub, Amazon ECR, and Google Artifact Registry are supported, but vite dev cannot pull directly from the Cloudflare Registry.

If you use a private Docker Hub, Amazon ECR, or Google Artifact Registry image in local development, authenticate to that registry locally, for example with docker login.

Push images to the Cloudflare Registry

Both scheduling policies can use images that you push to the Cloudflare Registry yourself. With the durable_object policy, this is required for any image from Docker Hub, Amazon ECR, Google Artifact Registry, or another external registry.

Use images from other registries

If you want to use a pre-built image from another registry provider, first make sure it exists locally, then push it to the Cloudflare Registry:

docker pull <PUBLIC_IMAGE>
docker tag <PUBLIC_IMAGE> <IMAGE>:<TAG>

Wrangler provides a command to push images to the Cloudflare Registry:

npmyarnpnpm

npx wrangler containers push <IMAGE>:<TAG>

yarn wrangler containers push <IMAGE>:<TAG>

pnpm wrangler containers push <IMAGE>:<TAG>

Or, you can use the -p flag with wrangler containers build to build and push an image in one step:

npmyarnpnpm

npx wrangler containers build -p -t <TAG> .

yarn wrangler containers build -p -t <TAG> .

pnpm wrangler containers build -p -t <TAG> .

This will output an image registry URI. With the default scheduling policy, you can use this tag reference in your Wrangler configuration:

{
    "containers": [
        {
            "image": "registry.cloudflare.com/<YOUR_ACCOUNT_ID>/<IMAGE>:<TAG>"
        }
    ]
}

[[containers]]
image = "registry.cloudflare.com/<YOUR_ACCOUNT_ID>/<IMAGE>:<TAG>"

With the durable_object scheduling policy, a named image source requires a digest-pinned reference. Get the digest of the pushed image first.

Get the digest of a pushed image

After you push an image, list its repository digests with Docker:

docker image inspect --format '{{join .RepoDigests "\n"}}' registry.cloudflare.com/<YOUR_ACCOUNT_ID>/<IMAGE>:<TAG>

Use the entry that starts with registry.cloudflare.com/ as a named image source:

{
    "containers": [
        {
            "class_name": "AgentComputer",
            "scheduling_policy": "durable_object",
            "images": {
                "tools": {
                    "image": "registry.cloudflare.com/<YOUR_ACCOUNT_ID>/<IMAGE>@sha256:<DIGEST>",
                },
            },
        },
    ],
}

[[containers]]
class_name = "AgentComputer"
scheduling_policy = "durable_object"

[containers.images.tools]
image = "registry.cloudflare.com/<YOUR_ACCOUNT_ID>/<IMAGE>@sha256:<DIGEST>"

Push images with CI

To use an image built in a continuous integration environment, install wrangler then build and push images using either wrangler containers build with the --push flag, or using the wrangler containers push command. With the durable_object scheduling policy, get the digest of the pushed image before you update your Wrangler configuration.

Registry limits

Images are limited in size by available disk of the configured instance type for a Container.

Delete images with wrangler containers images delete to free up space, but reverting a Worker to a previous version that uses a deleted image will then error.

Was this helpful?

YesNo

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/containers/guides/image-management/#page","headline":"Image Management","description":"Configure and update Container images with the durable_object and default scheduling policies.","url":"https://developers.cloudflare.com/containers/guides/image-management/","inLanguage":"en","image":"https://developers.cloudflare.com/containers/guides/image-management/og.png?v=3fd9a8c2d3fb3253","dateModified":"2026-09-30","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Learn how to run Container-enabled Workers locally with wrangler dev and vite dev. title: Local Development image: https://developers.cloudflare.com/containers/guides/local-dev/og.png?v=a2f82e93548ea4bd

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/containers/llms.txt
Use this file to discover all available pages before exploring further.

Image Management·续

Image Management·续

Use private Amazon ECR images

Use private Google Artifact Registry images

Push images to the Cloudflare Registry

Use images from other registries

Get the digest of a pushed image

Push images with CI

Registry limits

On this page