drift Docs
Pages
drift Docs
Start
What is Drift?
The tour, if you are new here.
Use cases
Whether Drift does your thing.
Getting started
Nothing to deployed, in one command.
Architecture
How a slice is put together.
What it costs
The free grant, four unit prices, two rules.
Moving off Azure
Estimate, snapshot and transform a resource group.
Build
Canvas
Static sites, same origin as your API.
Tools
Operate
Auth
Route gates, API keys and your account.
Teams
More than one person on one account.
Security
Boundaries, sandboxing and hardening.
Troubleshooting
Error codes
What went wrong, and what to do about it.
Legal
Acceptable use
What a slice may not be used for.
Data processing
The DPA, and every sub-processor.

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.

A React (or Vue, or plain-HTML) app deployed on Canvas fetches /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.

Driftfile
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/itemsAtomic → the function "GET /items"
POST /api/itemsAtomic → the function "POST /items"
/trigger/…Atomic → the trigger surface
GET /health, GET /readyThe slice's own health checks
/deploy, /prune, /admin/sitesCanvas's operator surface: what the CLI's deploy path calls
GET /Canvas → index.html
GET /styles.cssCanvas → 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.

A CDN <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.

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 one index.html.
  • Pre-rendering A static export writes users/42/index.html into 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.

A visitor arrives at /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:

Driftfile
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 site

So 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.

The slice's prune endpoint takes a keep-list rather than a name, and nothing in the CLI sends it. Redeploying a different folder at the same route replaces its contents, which is the closest thing available today.

Limits

ValuePast it
  • Upload body
    Value
    100 MB
    Past it
    413, nothing is deployed
  • ZIP payload vs. the slice's Canvas size
    Value
    50 MB on the free tier
    Past it
    413, nothing is deployed
  • Files per site
    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.

Canvas extracts an upload into a staging directory and only swaps it into place once the whole archive validates, so a site over 10,000 files gets the same 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:

Driftfile
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:

Driftfile
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.

Shell
drift plan
drift apply

drift 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:

Driftfile
edge {
  domain "yoursite.com" {}
}

Then the commands check on it:

Shell
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 routing

Hostnames 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:

Driftfile
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.

Each subdomain gets its own certificate, issued on first request. And the public hostname does not reach your functions: the edge rewrites 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:

Driftfile
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:

Shell
drift slice auth list                  # shows whether it's on, and who can sign in
drift slice auth disable               # takes it off again, after a confirmation

A 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.