Binding reference Bindings

Use Containers in a Worker

Containers let a Worker hand requests to stateful code running from a container image.

Add the Containers config, call Container class config plus a Durable Object container binding from worker code, and start with the local test path Devflare supports.

Start with the config, wire the binding into worker code, then use the support section to decide whether local tests or Cloudflare-backed tests fit.

Config key
Authoring shape
Best for: routing requests to a stateful container instance that runs code outside the Workers runtime

Add the binding to config

Add to , then use the generated env binding from Worker code.

Keep the first version close to the route or handler that needs it; move to a helper only after the shape is obvious.

Smallest Containers config

import { defineConfig } from 'devflare/config'

export default defineConfig({

name: 'container-worker',

files: {

fetch: 'src/container.api.ts',

durableObjects: 'src/container.api.ts'

bindings: {

durableObjects: {

API_CONTAINER: {

className: 'ApiContainer'

}

containers: [

{

className: 'ApiContainer',

image: 'localhost/devflare-api:latest',

imageBuildContext: './containers/api',

maxInstances: 1

}

migrations: [

{

tag: 'v1',

new_sqlite_classes: ['ApiContainer']

}

]

})

Use the binding from application code

After Devflare generates the worker env, import from and keep the first Containers path close to the route, handler, or service method that needs it.

Keep this first path small enough that the config, env binding, and user-visible behavior are easy to review together.

Proxy one application route to a container instance

import { Container, getContainer } from '@cloudflare/containers'

import { env } from 'devflare/runtime'

export class ApiContainer extends Container {

defaultPort = 8080

sleepAfter = '10m'

}

export async function fetch(request: Request): Promise<Response> {

const url = new URL(request.url)

const sessionId = url.searchParams.get('session') ?? 'public'

const container = getContainer(env.API_CONTAINER, sessionId)

return container.fetch(request)

}

Local and Remote Support

Devflare can run useful Containers application behavior locally for ordinary development and tests. Cloudflare still owns production limits, quotas, billing, and deployed account behavior.

Containers have full local support when Docker or Podman is reachable and the image can be built or inspected without Cloudflare. Devflare builds Dockerfile paths offline-first, runs the container on loopback, and exposes fetch, logs, state, stop, and destroy helpers. Cloudflare still owns deployed rollout, registry availability, SSH, scaling, and hosted platform behavior.

Use Cloudflare when the assertion depends on deployed limits, account state, lifecycle behavior, billing, or other production-only Containers details.

Build and reference the image deliberately

Devflare treats the entry as the contract between the Worker class and a real container image. For local work, point at a tag that already exists in Docker or Podman, or point it at a local Dockerfile path that Devflare can build from files on disk.

Cloudflare uses the same container idea in the hosted lane: Wrangler accepts a Dockerfile path or an image reference. Dockerfile paths are built locally and pushed during deploy, while image references can come from the Cloudflare Registry, Docker Hub, or Amazon ECR.

Use or when you want Wrangler deploy to build and push from source.
Use for a local tag that Docker or Podman can inspect without a network pull.
Use for Cloudflare Registry images, Docker Hub names such as , or Amazon ECR image references when the hosted deploy should pull a prebuilt image.
Use when the image lives in a private external registry.

Build the local image with Docker or Podman

docker build -t localhost/devflare-api:latest ./containers/api

docker image inspect localhost/devflare-api:latest

podman build -t localhost/devflare-api:latest ./containers/api

podman image inspect localhost/devflare-api:latest

Reference that local image from Devflare config

import { defineConfig } from 'devflare/config'

export default defineConfig({

name: 'container-worker',

containers: [

{

className: 'ApiContainer',

image: 'localhost/devflare-api:latest',

imageBuildContext: './containers/api',

maxInstances: 1

}

]

})

Use a Dockerfile or registry image for the Cloudflare lane

wrangler containers build ./containers/api -t devflare-api:latest

wrangler containers push devflare-api:latest

# Cloudflare can also reference registry images such as:

# registry.cloudflare.com//devflare-api:latest

# docker.io/library/nginx:alpine

# .dkr.ecr..amazonaws.com/devflare-api:latest

Full local support requirements

Full local support means Devflare can build, launch, call, inspect, and clean up the container without Cloudflare when the local machine has a working Docker or Podman engine.

The offline-first default is strict: Dockerfile builds use cached base layers, and image references must already exist locally. Set only when the test is allowed to pull from a registry.

Install Docker or Podman and make sure or succeeds before running container tests.
Set for test lanes that are allowed to start local containers.
Gate CI and hosted runners with because GitHub Actions, Cloudflare runners, and preview workers may not expose a usable container engine.
Keep base images cached when running offline. A missing local tag or uncached base layer is a setup problem, not a reason to silently reach out to a registry.

Run a container-backed route test only when the engine is available

import { afterAll, expect, test } from 'bun:test'

import { containers, shouldSkip } from 'devflare/test'

const skipContainers = await shouldSkip.containers

afterAll(() => containers.stopAll())

test.skipIf(skipContainers)('proxies to the local API container', async () => {

const api = await containers.start('ApiContainer', {

configPath: 'devflare.config.ts',

port: 8080,

offline: true

})

const response = await api.fetch('/health')

expect(response.status).toBe(200)

})

When this binding fits best

Use Containers when routing requests to a stateful container instance that runs code outside the workers runtime.
Keep binding names stable and uppercase in examples so generated Env declarations remain predictable.
Prefer Devflare native config while it covers the feature; use only for unsupported Wrangler-only fields.

Testing path

Start with containers helpers guarded by for config-backed local worker tests.
Use / / for small unit tests that only need deterministic application behavior.
Use Cloudflare-backed tests when the assertion depends on hosted platform behavior, account state, limits, billing, or production routing.

Open the next page when you need it

Subpage

Containers internals

Internals

Check emitted Wrangler , preview behavior, and Cloudflare-specific details.

Subpage

Testing Containers

Testing

Pick the containers helpers guarded by path first, then move to remote checks only when the test needs them.

Subpage

Containers example

Example

Copy a fuller application path when the quick example is too small.