Getting started
We'll build a small guestbook: a page with a form, an API that stores and lists the messages, and a database behind it. Along the way you'll touch three of Drift's services: Atomic for the API, Backbone for the data, and Canvas for the site, and never leave your terminal.
Everything you deploy lands in a slice: your project's own private corner of Drift,
with its own functions, data, site and URL, isolated from everyone else's. A single file, the
Driftfile, declares the slice and what runs on it. You write it
in step 6, preview what it would do in step 8, and drift apply creates the slice and
deploys into it in step 9.
1. Install the CLI
Everything on Drift happens through the drift command-line tool. Every release publishes
two install paths. Homebrew is the shortest, because it fetches a prebuilt binary, so there's no
toolchain to install and nothing to compile:
brew install ondrift/tap/driftAlready have Go? This builds the same CLI from source:
go install github.com/ondrift/cloud/cli/cmd/drift@latestEither way, confirm it's there. Three lines come back and they move independently: the version of this binary, the Driftfile format it implements, and the format cached on this machine, which can run ahead of both once the platform has moved on.
drift --version2. Get an account
Drift is in closed alpha, so signing up needs an invite code. During the closed alpha, invites are given by the Drift team and are not requested; open alpha will come later. A code is minted for one specific email address and works once. If you have one, redeem it and choose your own username and password:
drift account create --invite-code <code>The CLI asks for a username (2–32 lowercase letters and digits, with no hyphens or underscores), your email address, and a password of at least twelve characters, typed twice. The email has to be the one the code was issued for; anything else is refused. The invite code stands in for the emailed verification code, so there's no second round trip to wait for:
Username: alice
Email: alice@example.com
Password: ********
Repeat password: ********
Sending verification code...
Invite-only alpha — skipping email verification (your invite code is the gate).
Welcome to Drift, alice!
Next steps:
1. Write a Driftfile :: 'drift file new'
2. See what it creates, and what it costs :: 'drift plan'
3. Create the slice and deploy :: 'drift apply'
Manage slices :: 'drift slice list'
Happy building!A password is also checked against a list of known-breached passwords, so a long one that has appeared in a public breach is refused: length alone does not make a password an attacker will not try first. There are no character-class rules: mixing in a digit and a symbol produces predictable substitutions rather than a stronger password, so Drift asks for length and screens the result instead.
In CI, keep the password out of shell history.
ps:
echo "$PASS" | drift account create -u alice -e alice@example.com --password-stdin --invite-code <code>
Creating the account logs you in. On another machine, sign in with the credentials you chose:
drift account loginIt answers Logged in as alice. The session lands in ~/.drift/session.json, bound to a per-machine device ID, so this is
a one-time step on each machine.
3. Lay out the project
A Drift project is folders and a Driftfile. Atomic
source files sit flat under atomic/, with no per-function folders and no
list to maintain; your site lives under canvas/. Make the folder and step into it:
mkdir guestbook && cd guestbookHere's the shape we're about to build:
-
guestbook/the project root
-
atomic/every function's source, flat
- sign.goPOST, save a message
- entries.goGET, list messages
- go.modwritten by the scaffold
-
canvas/the site, served at /
- index.htmlthe page visitors see
- Driftfilewhat the slice is made of
-
atomic/every function's source, flat
4. Write the API
A function is a normal function in a normal source file. Nothing in the code marks it as special: no decorator, no framework, no base class. How it is reached is declared in your Driftfile in a moment. Scaffold one source file per endpoint, naming the language and the HTTP method:
drift atomic new sign -l go -m post
drift atomic new entries -l go -m get
The first command writes atomic/sign.go and the go.mod beside it, and prints
the block that declares it, which is what step 6 assembles:
✅ Added sign.go to the default backend (go, HTTP POST)
atomic/sign.go
atomic/go.mod
Declare it in your Driftfile, inside backend "default" of the atomic block (add the blocks if they are not there yet, or just the function block if they are):
atomic {
backend "default" {
function "POST /sign" {
handler = "PostSign"
memory = "32MiB"
}
}
}
Then:
drift plan # what applying it creates, and what it costs
drift apply # ship it
drift size # book what it has actually cost, once it has served traffic
Replace the scaffolded body with the endpoint that saves a message, in Go
(atomic/sign.go):
package main
import drift "github.com/ondrift/cloud/sdk/go"
func PostSign(body map[string]any, _ drift.Request) (int, string, any, map[string]string) {
id, _ := drift.Backbone.NoSQL.Collection("guestbook").Insert(body)
return 201, "Created", map[string]any{"id": id}, nil
}And the one that lists messages back (atomic/entries.go):
package main
import drift "github.com/ondrift/cloud/sdk/go"
func GetEntries(_ drift.Request) (int, string, any, map[string]string) {
all, _ := drift.Backbone.NoSQL.Collection("guestbook").List(nil)
return 200, "OK", all, nil
}
Every handler returns the HTTP status, a short status message, and the response body (the SDK
serialises objects to JSON for you). Go adds a fourth value, a response-headers map,
nil when you don't need one; Python, Node, Ruby, PHP and Rust return the three values
only. There is no router to wire up and no main() to write: Drift generates the
entry point around your handler. The scaffold names a handler from its method and route
(PostSign, GetEntries), and the Driftfile's handler is what
binds the name to the route, so you can rename it by editing both.
A handler has to be reachable from outside its own file.
pub fn in Rust, a named function rather than an arrow
assigned to a const in Node. The generated entry point imports it by name, so a
lowercase handler cannot be bound, and the CLI says so before it builds anything, naming the
callables it did find.
There is no database to set up.
drift.Backbone.NoSQL.Collection("guestbook") is the data layer, and the SDK talks to
Backbone for you. The collection does have to be declared before
you write to it: step 6 below is where guestbook gets declared, and a write to a
collection the slice does not have is refused with 400 rather than creating one.
5. Add the page
Canvas hosts your static site. Its best trick: a Canvas page can call its own functions on the
same origin, so the browser just fetches /api/sign and
/api/entries, with no CORS to configure and no separate API domain. Save this as
canvas/index.html:
<h1>Guestbook</h1>
<form id="form">
<input name="name" placeholder="Your name" required>
<input name="message" placeholder="Your message" required>
<button>Sign</button>
</form>
<ul id="entries"></ul>
<script>
fetch("/api/entries").then(r => r.json()).then(rows => {
rows.forEach(e => entries.innerHTML += `<li><b>${e.name}</b>: ${e.message}</li>`);
});
form.onsubmit = async (ev) => {
ev.preventDefault();
await fetch("/api/sign", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(Object.fromEntries(new FormData(form)))
});
location.reload();
};
</script>6. Declare it in a Driftfile
The Driftfile ties the project together. It names the slice
this project deploys into, says which of your source files fill which functions, and states the shape:
how much memory each function books and how big each collection is. Save this as Driftfile
at the project root. (drift file new writes a starter with the same blocks and a
comment on each, and drift file explain lists every block the file can hold.)
# The slice this project deploys into. A shape inside the free slice can be one of your free slices.
slice "guestbook" {}
atomic {
backend "default" {
function "GET /entries" {
handler = "GetEntries"
memory = "16MiB"
}
function "POST /sign" {
handler = "PostSign"
memory = "16MiB"
}
}
}
# The collection the functions read and write.
backbone {
nosql "guestbook" {
size = "16MiB"
}
}
# The site, served at the slice's root.
canvas {
site "/" {
dir = "canvas"
}
}
This file is the whole declaration. A function's label is the HTTP method and the route it answers on:
"POST /sign" is reachable at /api/sign. handler is which
callable in atomic/ serves it, and memory is what it books, with no
default, since every function states what it needs. A function the file does not name is not deployed at
all, which is deliberate: one that reached production without appearing here would be one the
platform could neither size nor price. The same goes for storage: each collection, database and
bucket states its size, because that is what it is billed at.
Anything else in your source is a helper. It costs nothing, is never routed, and can sit in the same file as a handler without changing either fact.
Both of these do very little: read or write one collection and return, so they book near their
floor and cost pennies. That floor is 16MiB here because these are Go: a compiled
function carries its own language runtime per invocation, where an interpreted one shares a
language server and can book as little as 8MiB. If you don't know what to write,
deploy once and let the slice measure: step 12 shows how drift file benchmark and
drift size turn what each function actually needed into the number to write.
This shape is inside the free slice, which is what a first project runs on, so there is nothing to pay. Check the file, then print what it resolves to. Both run on your laptop, with no account and no network:
$ drift file lint
✓ Driftfile is valid (slice "guestbook")
$ drift file resolve
slice guestbook (fits a free slice)
────────────────────────────────────
functions (2)
· function GET /entries 16MiB
· function POST /sign 16MiB
nosql (1)
· guestbook 16MiB
limits
· slots 2
sites (1)
· / canvas
the price comes from the platform: drift plan
Resolve prints what the file states and nothing it leaves out. The slots are the number of functions
and workers, and the limits you do not write are the platform's own figures, the free slice's when
the shape fits it. A shape that is bigger than the free slice is priced: drift plan says
which bound it crossed, and drift apply asks you to agree to the price first.
Every booking and every size is written, and nothing else is required.
7. Run it locally
Before anything touches Drift, run the whole project on your own machine. It needs Docker and nothing else: each language builds in a throwaway container, so no toolchain has to be installed.
drift file runIt builds the functions and the site, bakes them into a thin image on the Drift runtime, and launches it:
✓ guestbook running (container drift-guestbook)
→ http://127.0.0.1:8002/
drift file logs · drift file stopOpen that address to use the page, or call the API on it. The code is the code that runs on Drift:
# sign the guestbook, locally
curl -X POST http://127.0.0.1:8002/api/sign \
-H "Content-Type: application/json" \
-d '{"name": "Alice", "message": "Hello from my laptop!"}'
# read it back
curl http://127.0.0.1:8002/api/entries
# tail the logs, then tear it down
drift file logs -f
drift file stop
Backbone data lives only as long as the container unless you pass --persist, which
keeps it in a named volume across runs (drift file stop --purge removes the volume too).
--port picks the host port; by default it is 8002, or the next free one.
8. Plan the slice
A slice is a thing you buy, so you see what applying the file would do, and what it costs, before it
does anything. drift plan compares the Driftfile with the live slice, prints every
difference, and changes nothing. Here the slice does not exist yet, so everything is an addition:
$ drift plan
slice alice/guestbook + create
+ function GET /entries books 16MiB, and deploys
+ function POST /sign books 16MiB, and deploys
+ nosql guestbook 16MiB
+ site / uploads canvas
+ slots 5
+ databases 1
+ limits.requests_per_minute 60
+ limits.timeout 10s
+ limits.log_retention 24h
+ limits.deploy_history 1
+ limits.backup_retention 3d
+ limits.scheduled_jobs 1
+ limits.atomic_storage 100MiB
+ limits.canvas_storage 50MiB
+ limits.realtime_connections 50
+ limits.secrets 5
+ limits.secret_size 1KiB
+ limits.locks 100000
+ limits.blob_object_size 5MiB
+ limits.queue_depth 500
+ limits.vault_entry_size 4KiB
+ limits.vault_entries 100
+ limits.pocket_record_size 16KiB
Price free (quoted by the platform)
Restart no: the slice is created
Removes nothing
Apply with: drift apply (asks for each of the above)
The price line is the platform's own quote, never a figure the CLI worked out, so the number you
see is the number you agree to. Billing starts later; the closed alpha charges nothing. A slice whose shape is outside the free slice shows a monthly figure
there, and applying it asks you to agree to it. Marks down the left edge say what each line does:
+ adds, ~ changes, - removes, and a blank leaves it as it is.
See drift plan for all of them.
The function itself is free. You pay for the memory it books and the disk its deployed code occupies, and nothing for its existence, so splitting one function into six costs what the one cost, as long as the memory adds up the same. See what it costs for the full price list and the free grant, and memory and concurrency for what that booking buys you at run time.
9. Apply it
Now one command creates the slice, then compiles and ships both functions and publishes the site into it:
drift apply
It prints the same plan, and asks before three things, each on its own: a monthly price that moves,
anything it removes, and any data that could be lost. Agreeing to a removal is not agreeing to lose
what it holds. This plan asks nothing, because the slice is free and nothing is removed. Without a
terminal, each question is answered by a flag instead
(--approve-price, --approve-remove, --allow-data-loss), and an
unanswered one stops the apply before anything is sent. It ends with a tick and the slice's address.
See drift apply for the order it works in.
The file declares the shape, and apply makes the slice match.
drift apply creates the slice when it does not exist, resizes it when the file's shape
differs from the live one, then deploys what runs on it. Running it again changes nothing: a function
whose source and declaration are unchanged is skipped (--force redeploys every one).
Changing the shape in either direction is an edit to the file and another
drift plan.
10. See it live
Your slice answers at <username>-guestbook.ondrift.eu, with TLS handled for you. Open
that URL to use the guestbook in the browser, or hit the API directly:
# sign the guestbook
curl -X POST https://<username>-guestbook.ondrift.eu/api/sign \
-H "Content-Type: application/json" \
-d '{"name": "Alice", "message": "Hello from Drift!"}'
# read it back
curl https://<username>-guestbook.ondrift.eu/api/entries11. Inspect it, and give it a secret
You can read and poke at your slice's data without leaving the shell:
# list what's in the guestbook collection
drift backbone nosql list --collection guestbook
# push a message onto a queue
drift backbone queue push notify '{"to": "alice", "text": "welcome!"}'
# cache a value for an hour
drift backbone cache set greeting "hello world" --ttl 3600
# list the secrets the slice holds (names only)
drift backbone secret list
# check the slice's health and usage
drift backbone status
A secret is declared in the Driftfile like everything else, and its value is never written there.
The secret block reads it from an environment variable at apply time, and the function that
needs it names it in secrets:
atomic {
backend "default" {
function "POST /sign" {
handler = "PostSign"
memory = "16MiB"
secrets = ["API_KEY"]
}
}
}
backbone {
secret "API_KEY" {
value = env("API_KEY")
}
}
Give env() its value from the terminal, with --var, or in a
.env file beside the Driftfile (in that order of precedence), and apply:
API_KEY=sk-12345 drift apply
# or
drift apply --var API_KEY=sk-12345
If the variable is not set, the plan marks the secret with ! and apply refuses before
sending anything. A secret is write-only: the plan never reads a value back, it sets each declared
one again from its variable on every apply. And because the file is the whole declaration, a secret
the slice holds that the file does not name appears in the plan as - secret NAME and
is deleted if you agree, so a secret set only with
drift backbone secret set does not survive an apply that omits it.
A function only receives the secrets it names.
secrets list. The runner fetches each named
secret on every call and passes it in as DRIFT_SECRET_API_KEY, so changing a
value takes effect on the next request with no redeploy. Adding a name to the list is the part that
needs one.
Bare drift opens the same data in a full-screen terminal dashboard, with slices down
the side, and Atomic / Backbone / Canvas panes for browsing functions, documents and sites.
12. Book what it measured
The slice weighs every function invocation and samples every field. Once your guestbook has served some traffic, ask what each one really needed:
drift file benchmark
benchmark only reports: the calls behind each peak, the peak itself, what is booked, and
the size to book instead. A function nobody has called yet says so rather than reporting a
confidently small number. drift size writes those recommendations into the
memory lines of your Driftfile, keeping comments and layout, and shows the change as a
diff (--dry-run shows it without writing). Nothing is bought by it: run
drift plan to see what the new bookings cost, then drift apply as for any
other edit.
Free, monthly, and slices without a file
A Driftfile does not say how the slice is paid for: its shape does. The same file works for both:
| Shape | What it means |
|---|---|
| Inside the free slice | It can be one of your free slices: up to three per account, at €0. drift apply asks You have 1 of 3 free slices and whether to make this the next. When you hold all three it refuses and names them. |
| Anything else | Priced per unit. drift plan quotes the monthly figure and drift apply asks you to agree to it. |
A file that would move an existing free slice to a priced shape is refused for now: that move is made with
drift slice resize. To
start a new slice, write its Driftfile with drift file new, which asks for the name
and the first function, and run drift apply. From then on a command run anywhere inside the project acts on
that project's slice, because the Driftfile names it; set DRIFT_SLICE=<name> to act on
another.
The free slice's limits are fixed; its shape is yours.
Write in your language
Functions can be written in Go, Python, Node.js, Ruby, PHP, or Rust, and the CLI detects the language from your source files. The same "sign" endpoint looks like this in Python…
import drift
def post_sign(body, req):
entry_id = drift.backbone.nosql.collection("guestbook").insert(body)
return 201, "Created", {"id": entry_id}…and in Node.js:
const drift = require("@ondrift/sdk");
async function postSign(body, req) {
const id = await drift.backbone.nosql.collection("guestbook").insert(body);
return [201, "Created", { id }];
}
module.exports = { postSign };
The handler's name is yours to choose: post_sign here, but it could be
sign_guestbook as long as the Driftfile's handler says so.
drift apply handles every language the same way: it reads your Driftfile,
finds each declared handler in its backend's folder, and ships them together. It builds
and uploads only the functions and workers whose source or declaration changed since the last
apply, so running it again after a small edit is quick.
Rust takes one function per folder.
Take your data and go
Drift has no lock-in. At any point you can snapshot a slice and download the whole thing: source code, database contents, secrets, and static sites. Your source comes back as you wrote it, with every Drift-generated wrapper stripped out, and the only Drift files in the archive are two manifests sitting beside the tree:
drift slice snapshot create --name my-backup
drift slice snapshot download <snapshot-id>Optional: use your own domain
Your slice answers at <username>-guestbook.ondrift.eu, and you can point your own
hostname at it, and Drift verifies ownership and issues the TLS certificate for you. Declare the
domain in the Driftfile, in the edge block, and let the next
drift apply attach it. Verifying stays a command, because it needs your DNS to be live
first.
edge {
domain "guestbook.example.com" {}
}The apply prints two DNS records to create at your registrar:
# 1. prove you own the domain
_drift-challenge.guestbook.example.com. TXT "drift-verify=<token>"
# 2. route the hostname to your slice
# (or an A record to the platform's IP at a zone apex, where CNAMEs aren't allowed)
guestbook.example.com. CNAME ingress.ondrift.eu.Once DNS has propagated, verify. Drift checks the TXT record and marks the domain live; the certificate itself is issued on demand, the moment the first request for it arrives:
drift slice domain verify guestbook.example.comWatch it go live (and see every domain on the slice) with:
drift slice domain listWhen the status reads live, your guestbook is served on your own domain, HTTPS and all.
drift account
drift file
drift plan
drift apply
drift size
drift slice
drift atomic
drift backbone