# Containers

> Decide when to use Cloudflare Containers instead of Workers and design container-backed workloads, native binaries, long-running processes, image processing, larger runtime shapes, and Worker frontends. Use as an escape hatch when Workers constraints do not fit.

- Skill: `zllovesuki/containers` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zllovesuki/containers`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zllovesuki/containers/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: zllovesuki (https://skillmd.com/u/zllovesuki)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/zllovesuki/containers

---

# Containers

Use this skill when evaluating or implementing Cloudflare Containers. Containers are an escape hatch for workloads that do not fit the Worker runtime shape.

## Use Containers when

- The code requires native binaries or a runtime that cannot reasonably run in Workers.
- The workload needs a process model unavailable in Workers.
- The task is CPU/memory/runtime-shape heavy and cannot be solved by streaming, chunking, R2, Queues, or Workflows.
- You are bringing an existing service to Cloudflare while incrementally refactoring.

## Prefer Workers when

- The workload is HTTP request/response logic.
- It mostly orchestrates I/O through bindings.
- It can be implemented with Web APIs and small compute slices.
- The primary need is global low-latency routing, not a persistent process.

## Design pattern

Put a Worker at the edge as the public interface and use Containers only for the specialized work.

```text
Client
  -> Worker: auth, validation, routing, rate limiting
  -> Queue/Workflow: durable background orchestration when needed
  -> Container: native/heavy execution
  -> R2/D1: results and metadata
```

## Implementation guidance

- Make the container API narrow and explicit.
- Store inputs/outputs in R2 for large artifacts; pass keys, not blobs.
- Add idempotency keys for long-running work.
- Use Queues or Workflows for durable scheduling and retries.
- Keep authentication and tenant authorization in the Worker boundary.
- Capture logs and correlation IDs across Worker, queue/workflow, and container.

## Refactor-before-container checklist

Try these first when feasible:

- Stream files instead of buffering them.
- Move large blobs to R2.
- Split jobs into queue messages or workflow steps.
- Use Workers-native libraries or Web APIs.
- Push relational work to D1/Hyperdrive.
- Use Workers AI or external APIs through AI Gateway for inference.

## Anti-patterns

- Running a normal stateless API in a container only because it is familiar.
- Using containers to bypass clear Cloudflare platform mismatches without a cost/ops review.
- Keeping user authorization only inside container code while the Worker blindly proxies requests.
- Passing unbounded request bodies through the Worker and container without streaming or size checks.