Craft Cloud — Serverless Hosting for Craft CMS

Reference for Craft Cloud, Pixel & Tonic's serverless hosting platform for Craft CMS. Covers the craft-cloud.yaml config file, the Build → Migrate → Release deploy pipeline, the craftcms/cloud extension, edge image transforms and static caching, the Cloud filesystem, plugin Cloud-compatibility requirements, and self-hosted → Cloud migration.

This skill is scoped to Craft Cloud specifically — what's different on Cloud vs running Craft yourself on Forge, Servd, or bare metal. For Servd, see the servd skill. For generic Craft deployment (build artifacts, project config sync, atomic deploys on traditional hosts), see the craftcms skill's deployment.md.

Companion Skills — Load When Needed

• craftcms — When the Cloud topic intersects plugin or module PHP work (e.g. App::isEphemeral() guards in services, asset-bundle constraints, queue job design for the 15-minute cap).
• craft-site — When Cloud intersects front-end templating (ESI islands inside cached pages, edge image transform usage, {% expires %} opt-outs for static caching).
• ddev — For the local-dev parity recipe (matching PHP/DB versions, simulating the ephemeral filesystem locally).
• craft-php-guidelines — When editing plugin PHP to add Cloud-compatibility checks.

Documentation

Authoritative sources used to write this skill:

• Craft Cloud docs landing: https://craftcms.com/docs/cloud/
• Configuration reference: https://craftcms.com/docs/cloud/config
• Deployment pipeline: https://craftcms.com/docs/cloud/deployment
• Builds: https://craftcms.com/docs/cloud/builds
• Compatibility & limitations: https://craftcms.com/docs/cloud/compatibility
• Assets & transforms: https://craftcms.com/docs/cloud/assets
• Static caching: https://craftcms.com/docs/cloud/static-caching
• Headless apps: https://craftcms.com/docs/cloud/headless-apps
• Request signing: https://craftcms.com/docs/cloud/request-signing
• Plugin development: https://craftcms.com/docs/cloud/plugin-development
• Cloud extension source: https://github.com/craftcms/cloud-extension-yii2

Per-claim URLs appear in each reference file. Last verified against the docs and craftcms/cloud-extension-yii2@main on 2026-05-28; headless/request-signing, artifact URLs, environments, quotas, and backups content verified against craftcms/docs@main on 2026-09-02.

What's Different on Cloud vs Self-Hosted

A quick orientation table. Each row is a place self-hosted habits will mislead you.

Common Pitfalls (Cross-Cutting)

• Writing to disk without an App::isEphemeral() guard. Lambda's filesystem is ephemeral and writes are lost between requests. Plugins, services, and migrations all need to check and use the Path service (Craft::$app->getPath()->getTempPath()/getStoragePath()/getCachePath()) for transient writes. See references/extension.md (App::isEphemeral) and references/plugin-development.md.
• Reconfiguring Cloud-owned app components in config/app.php / app.web.php / app.console.php. The craftcms/cloud extension augments the response component (header normalization, gzip, binary→S3 offload, all attached on EVENTAFTERPREPARE) and replaces session, cache, mutex, queue, and assetManager — plus auto-wires the database connection. Redefining or augmenting any of these in your app config collides with that wiring and can return HTTP 500 on every request (and bypass edge caching). This includes the DB: don't configure db.php or set CRAFTDB env vars. To add response logic (e.g. a Content-Language header), attach at runtime to the response instance from a module — Craft::$app->getResponse()->on(\yii\web\Response::EVENTAFTERPREPARE, …) — never redefine the response component. And never validate these changes locally: the extension only runs on Cloud (Helper::isCraftCloud() is false on DDEV), so a local HTTP 200 proves nothing — treat app..php as prod-only-verifiable. See references/database.md and references/extension.md.
• Using tablePrefix. Unsupported on Cloud. Run php craft db/drop-table-prefix before migrating. See references/migration.md.
• Choosing MariaDB. Cloud only supports MySQL 8.0 and Postgres 15.
• Scheduling your own queue runner. Cloud auto-processes queue jobs — adding a scheduled command for the queue runner is redundant and may conflict.
• Flushing the whole cache from a migration. Craft::$app->getCache()->flush() (or any global wipe) during the Migrate phase contends with the still-live old version on a shared cache — and when Redis/Valkey isn't provisioned, that cache is a single MySQL table, so a flush can deadlock (MySQL 1205) and blow the deploy's CLI cap. Invalidate only what changed. See references/deploy-pipeline.md (Never flush the whole cache from a migration) and references/extension.md (Cache, queue, and session wiring).
• Synchronous external HTTP in element save hooks. Blocks every save, and during a resave or cloud/up serializes network latency into the deploy's CLI cap. Queue the call instead. See references/plugin-development.md.
• Trying to schedule cron more often than hourly. Cloud's UI enforces a one-hour minimum. Design recurring tasks around this floor or move the work into queue jobs triggered by other events.
• {{ csrfInput() }} in cacheable templates. Forces a cookie, busts edge static caching. Use the csrfInput() function instead, which renders an async input compatible with asyncCsrfInputs (force-enabled on Cloud).
• Expecting logged-in users to see currentUser-gated UI on a cached route. Cloud does not auto-bypass the edge cache for logged-in requests — once a URL's guest copy is cached, editors are served that copy too (cf-cache-status: HIT), so server-rendered edit links / member-only blocks silently disappear. Vary the cache key on the session cookie (cookies: [CraftSessionId]), not session:, under a nested cache: → rules: key. See references/caching-and-edge.md.
• .htaccess rules or nginx config in the repo. Won't be honored — move to redirects: / rewrites: in craft-cloud.yaml. See references/config-file.md.
• Writing to log files. No persistent filesystem. Use Craft::info/warning/error() and the logger routes to Cloud's log target automatically. See references/extension.md.
• Assuming SSH access. There is none. The Console command runner is the only way to execute commands, with a 255-character argument cap and 15-minute timeout.
• Forked Git repos. Cloud can't deploy from forks — must be the upstream repository.
• Expecting per-PR preview environments. Cloud supports per-branch environments only; no automatic ephemeral environment per pull request.
• Default sendmail adapter. Will not deliver mail. Configure SMTP/Postmark/SES/Resend explicitly. See references/limitations.md (Mail).
• Using ImageOptimize on Cloud. Cloud handles transforms at the edge via Cloudflare Images — ImageOptimize duplicates the work and can conflict. See references/assets-and-transforms.md.
• Unsigned automated traffic (SSG builds, ISR revalidation, CI) getting 429/503. Cloud's bot detection correctly flags headless content retrieval as bot traffic. Sign server-side requests with the environment's $CRAFTCLOUDSIGNING_KEY (RFC 9421) and retry 429/503 with Retry-After-aware backoff — signatures bypass the bot policy, not capacity limits. Never expose the key client-side. See references/headless.md.
• A robots.txt that blocks everything, or slow first requests, on a non-production environment. Cloud injects Disallow: / into every environment not marked Production, and lets non-prod functions sleep after ~15 min idle. Both are by design — check the Production Environment setting before debugging. See references/limitations.md (Environments).
• Changing a Console env var and expecting it to apply. Variable changes take effect only on the next deployment. See references/deploy-pipeline.md.

Reference Files

Read the relevant reference file(s) for your task. Multiple files often apply.

Task examples:

• "Set up a new Craft project on Cloud" → config-file.md + deploy-pipeline.md + extension.md
• "Configure craft-cloud.yaml for PHP and Node versions" → config-file.md
• "Add redirects in craft-cloud.yaml" → config-file.md (Redirects and Rewrites)
• "What happens during deploy?" → deploy-pipeline.md
• "Set build-time env vars" → deploy-pipeline.md (Build-time vs runtime variables)
• "Which env vars are reserved / shouldn't I set on Cloud?" → deploy-pipeline.md (Reserved runtime variables)
• "What does php craft cloud/up do?" → extension.md (cloud/up internals)
• "Add an ESI island inside a cached page" → caching-and-edge.md
• "Edge static caching rules" → caching-and-edge.md
• "Migrate user assets from self-hosted to Cloud" → assets-and-transforms.md + migration.md
• "Make this plugin Cloud-compatible" → plugin-development.md
• "Why does my plugin's file write silently fail on Cloud?" → plugin-development.md (Ephemeral filesystem) + extension.md (App::isEphemeral)
• "Set up a custom domain" → domains.md
• "Schedule a recurring command" → commands-and-cron.md (hourly minimum)
• "Run a one-off command on Cloud" → commands-and-cron.md (Console command runner)
• "Configure SMTP on Cloud" → limitations.md (Mail) + craftcms/email.md
• "Set up local DDEV to match Cloud" → local-dev.md
• "Move a self-hosted Craft site to Cloud" → migration.md
• "What plugins work on Cloud?" → limitations.md (Plugin compatibility — community knowledge)
• "My Next.js/Nuxt/Astro build gets 429s from Cloud" → headless.md
• "Sign programmatic requests to Cloud" → headless.md (Request signing)
• "Link built JS/CSS from templates" → deploy-pipeline.md (Artifact URLs)
• "Private Composer packages on Cloud" → deploy-pipeline.md (Private Composer packages)
• "robots.txt is blocking my site" → limitations.md (Environments)

Load only the reference files your task needs.