Canvas
Canvas serves your static files (HTML, CSS, JavaScript, images) and forwards any request under /api/* to your Atomic functions. Your frontend and your backend live at the same origin, so the browser calls /api/… with no CORS headers, no proxy config, and no separate API domain to manage.
There is no CORS to configure.
/api/items the way it would fetch a local file: same host, same TLS, one deploy. There is no CORS preflight to configure because there is no second origin.Declare a site
A site is a site block in the Driftfile's canvas block, naming the folder that holds its files. The block's label is where it mounts: / for the root, or a sub-path.
slice "demo" {}
canvas {
# serve a folder at the root
site "/" {
dir = "my-site"
}
# mount a folder under a sub-path
site "/admin" {
dir = "admin"
}
}drift apply zips each folder, uploads it, and serves it over HTTPS at your slice's URL. Applying again uploads each declared site again and replaces its files wholesale, so the files on the slice are the files in the folder. There is no drift canvas command: the Driftfile declares the site and drift apply ships it. No command takes a site away again, see Removing a site.
How routing works
Your slice answers every request on one public URL, and it checks a short list of reserved prefixes before it looks for a file. Order matters:
| Request | Handled by |
|---|---|
GET /realtime/<channel> | Backbone Realtime: the WebSocket upgrade, matched first |
GET /api/items | Atomic → the function "GET /items" |
POST /api/items | Atomic → the function "POST /items" |
/trigger/… | Atomic → the trigger surface |
GET /health, GET /ready | The slice's own health checks |
/deploy, /prune, /admin/sites | Canvas's operator surface: what the CLI's deploy path calls |
GET / | Canvas → index.html |
GET /styles.css | Canvas → the static file |
Everything that is not one of those prefixes is served as a static file. The reserved names belong to the platform, so a site mounted at / cannot serve its own /health or /deploy, and a wrong method on /deploy or /prune answers 405 rather than falling through to your files. A site mounted at a sub-route is unaffected: /blog/health is an ordinary file.
The /realtime/ intercept is why a browser subscribes at wss://<your-slice>/realtime/<channel>, and that URL is a Canvas route handed to Backbone's hub. See Backbone for the channel protocol.
Response headers
Every static response carries a fixed header set. There is no flag, Driftfile attribute or API to change any of it:
Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self'
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
Referrer-Policy: strict-origin-when-cross-origin
Permissions-Policy: camera=(), microphone=(), geolocation=()The CSP confines every subresource to your own origin.
<script>, a Google Fonts stylesheet (and its font files, which fall back to default-src 'self'), a remote image, and any fetch, XHR or WebSocket to another host are blocked by the browser. Vendor what you need into the folder you deploy. X-Frame-Options: DENY also means a Canvas site cannot be embedded in an iframe.Your own /api/* calls and /realtime/ socket are same-origin, so connect-src 'self' allows them. 'unsafe-inline' is granted to scripts and styles, so an inline <script> or a style attribute works. Content types come from the file extension, and Canvas answers a conditional If-Modified-Since request with 304.
Single-page apps
Deploy your framework's build output, the contents of dist/ or build/, like any other folder. Two rules about how paths resolve decide whether a client-routed app survives a refresh.
Deep links need a real file
There is no history-API fallback. A path with no file extension is treated as a directory and index.html is appended to it, so GET /users/42 resolves to users/42/index.html inside your site. A Vite or CRA build does not contain that file, and the answer is 404. The two ways to keep deep links working:
- Hash routing Paths take the form
/#/users/42. Browsers never send the fragment, so every request is for/and lands on your oneindex.html. - Pre-rendering A static export writes
users/42/index.htmlinto the folder you deploy, so the file genuinely exists. This only covers routes you can enumerate at build time.
The injected <base href>
When Canvas serves an HTML file that contains a literal lowercase <head> and no <base>, it inserts a <base href> pointing at the directory of the request URL, not at the route the site is mounted on. For a site deployed with --route /blog:
| Request | Injected |
|---|---|
/blog | <base href="/"> |
/blog/ | <base href="/"> |
/blog/index.html | <base href="/blog/"> |
A sub-route resolves its assets against the origin root.
/blog or /blog/, and both get <base href="/">, so relative asset paths resolve against the origin root and reach the root site or a 404. Build with the base path set to your route (--base=/blog/ in Vite, homepage in CRA) so the emitted URLs are absolute, or write your own <base href="/blog/">, which Canvas leaves alone.Injection is skipped when the document contains no lowercase <head> token, and when the bytes contain <base anywhere. A site mounted at / gets a base href that matches its own directory, so it needs none of this.
Multiple sites
A slice can host several sites, each at its own route. The longest matching route wins, so a site at / never shadows one at /blog whatever order they were uploaded in:
slice "demo" {}
canvas {
site "/" { dir = "marketing" }
site "/blog" { dir = "blog" }
site "/admin" { dir = "admin" }
}Each route becomes a slug that names the site's directory on the slice: / is default, /blog is blog, /admin/portal is admin-portal.
Removing a site
No drift command removes a site, and drift apply does not remove one either. A site the Driftfile does not name is left serving: a slice can host more than one project, and a deploy cannot tell a site that is not yours from one you meant to drop, so it does neither.
What the tools do instead is report it. drift plan lists it with a - mark (- site /admin still served: no drift command removes a site yet), and at the end of a run drift apply names every live resource the Driftfile does not, canvas sites among them:
· Live on this slice, and not named in this Driftfile:
canvas site admin
still served — no drift command removes a siteSo a site whose block you delete from the Driftfile, or one applied from another project, keeps serving on its route, and is named on every plan and every apply until you deal with it.
Taking a site away is currently a gap, and the report says so rather than pretending otherwise.
Limits
- Value
- 100 MB
- Past it
413, nothing is deployed
- Value
- 50 MB on the free tier
- Past it
413, nothing is deployed
- Value
- 10,000
- Past it
413, nothing is deployed
The size check is against the compressed ZIP of the deploy you are making, not the total across every site on the slice. Raise canvas_storage in the limits block of the slice (see the Driftfile) for more.
A refusal never touches what's already live.
413 refusal as the two size limits above rather than a partial deploy. Whatever was already live keeps serving until you trim the folder and redeploy.In a Driftfile
Declare your sites alongside everything else with one site block each, labelled with the route it is served at and written inside the file's canvas block, and ship them with one command:
canvas {
site "/" {
dir = "site"
}
site "/blog" {
dir = "blog"
}
}The first is mounted at / and the second at /blog. dir is relative to the Driftfile.
A full-stack app, meaning a frontend, an API, and its data, is one file with a Function, a collection and a site in it:
slice "my-app" {}
atomic {
backend "default" {
function "GET /items" {
handler = "GetItems"
memory = "32MiB"
}
}
}
backbone {
nosql "items" {
size = "64MiB"
}
}
canvas {
site "/" {
dir = "frontend/build"
}
}Every Function is listed. A function block is what turns a callable in your source into an endpoint; a function the file does not name is ordinary code and never gets a route. The block also carries the memory the Function books, which is what it is billed at, so naming it is the act: see Write a function.
drift plan
drift applydrift plan shows what the file would create and what it would cost; drift apply creates the slice when it does not exist (or resizes it to the file's shape when it does), then deploys. Your build is served at /, your functions answer at /api/*, and your data lives in Backbone, all on the same origin. See the Driftfile reference for every block and attribute.
Custom domains
Every slice answers at <username>-<slice>.ondrift.eu with TLS handled for you, and you can point your own hostname at it. Declare it as a domain block inside edge and run drift apply, which prints the DNS records to create:
edge {
domain "yoursite.com" {}
}Then the commands check on it:
drift slice domain verify yoursite.com # re-checks the TXT, then issues the certificate
drift slice domain list # host, status, wildcard, detail
drift slice domain remove yoursite.com # also drops its certificate and routingHostnames are an Edge rule; Hostnames and domains has the whole flow.
A subdomain per tenant
wildcard = true in the domain block routes every subdomain of a host to the same slice:
edge {
domain "imprente.com" {
wildcard = true
}
}alice.imprente.com, bob.imprente.com and every other subdomain reach the same Canvas site and the same functions. Drift delivers the request; the app decides what the subdomain means. The match strips one label, so a.b.imprente.com is not covered by a wildcard on imprente.com.
This is routing, not a wildcard certificate.
Host to the internal backend before proxying. Read location.hostname in the browser and send the tenant explicitly, in the path, the body, or a header of your own.Gating a site
A deployed site is public the moment it lands. To keep one off search engines and out of a shared link before it is ready, put an HTTP Basic-auth gate in front of it. Declare a site_auth block inside edge and run drift apply:
edge {
site_auth {
paths = ["*"]
user "visitor" {
password = env("VISITOR_PASS")
}
}
}paths says what the gate covers: ["*"] is every page, and a list such as ["/admin"] gates only that page and everything beneath it, leaving the rest of the site public. The block is the whole credential list, so naming one user is enough to lock everyone else out. The password is read from the environment variable when you apply, never written in the file or typed as a flag, so it never sits in the repository or in shell history. Two commands look after the gate:
drift slice auth list # shows whether it's on, and who can sign in
drift slice auth disable # takes it off again, after a confirmationA visitor with no credential gets the browser's own password prompt, then a 401 if they cancel or get it wrong.
The gate covers the Canvas paths you name, and only Canvas paths.
paths = ["*"] fronts every site the slice hosts, at every route; a narrower list fronts only those pages and what is beneath them. /api/* and /trigger/* pass through untouched, because both already read a credential from the same Authorization header a Basic-auth challenge would use, and gating them here would collide with an app's own Bearer tokens or API keys. Guard those with drift atomic auth instead.It is a soft wall for a site that is not ready to be found, not an authorization model: anyone holding the password reaches everything the gate fronts. The gate is an Edge rule, declared as the site_auth block inside edge; The site gate covers what a visitor sees and how the slice's Deed checks each password.