Deploy and run
Static sites
Serve a site that's only files (Vite, Astro, Next export, Hugo) from CLI's origin with CDN cache headers. No container, billed for bandwidth only.
Many sites are just files once they're built: a React or Vite app, a Hugo or Astro site, a landing page. Make it a static site and CLI serves the files directly, with nothing running in between, so you only pay for the bandwidth people use.
How to do it: CLI usually notices a static site by itself when you deploy. Otherwise open the app's Settings and turn on Static site, with the folder your build writes to.
New versions show up straight away, and files are cached for speed.
Plenty of sites are only files once they're built: a Vite or Create React App bundle, an Astro or Hugo site, a Next.js static export, a landing page. They don't need a container running all day. Make the service a static site and CLI builds it as usual, then serves the output folder itself.
- No container, so nothing runs while nobody visits. You pay for bandwidth only (5 cents per GB unless the operator changes it).
- Cache headers a CDN can use. Asset names with a content hash (
index-BkX9q2a1.js) are cached by browsers and CDNs for a year. HTML is revalidated every minute, so a new version shows up straight away. - Instant rollbacks. Each version is kept as its own set of files, and a rollback publishes the old version's files again.
Turn it on
On the service's settings, under Static site, give the folder your build writes to, then deploy.
PUT /v1/services/:id/static-site {"outputDir": "dist", "spa": false}
POST /v1/services/:id/deploys| Framework | Output folder |
|---|---|
| Vite, Vue, SvelteKit (static adapter) | dist or build |
| Create React App | build |
Next.js with output: "export" | out |
| Astro | dist |
Hugo, Jekyll (_site) | public |
Set spa: true for single-page apps with client-side routing. Unknown paths like /dashboard/settings then get index.html (missing files with an extension, like /logo.png, still return 404).
How paths are served
/and/docs/serveindex.htmlfrom that folder./pricingservespricing.htmlif there is one./docsredirects to/docs/whendocs/index.htmlexists.- A missing page serves your
404.htmlwith status 404 if you have one. - Only
GETandHEADare answered. Requests withIf-None-Matchget a 304 when nothing has changed.
The output folder must contain index.html. If it doesn't, the deploy fails with STATIC_PUBLISH_FAILED and the previous version keeps serving. Limits are 20,000 files and 1 GB per site.
Domains and the CDN
Custom domains work as they do for any app (/docs/domains-and-networking). If the operator puts Cloudflare in front of CLI and sets CLI_CDN_CLOUDFLARE_TOKEN and CLI_CDN_CLOUDFLARE_ZONE, CLI purges the site's hostnames on every publish.
GET /v1/services/:id/static-site shows the live files and the last day's requests, bytes and cost.
Back to a container
Run as a container instead (or PUT … {"enabled": false}) stops serving the files. The next deploy runs the app normally. Agents can do all of this with cli_static_site.