Wisp is in pre-release, self-hosted since GitHub suspended us. Install it, or see the changelog.

Wisp

Deploying

Run wisp build, copy the binary, run it. Pick the build for your host:

You haveUse
VPS or serverwisp host sets it up and keeps it running (Wisp Host). Or wisp build, then wisp service install (VPS)
Container host (Fly.io, Railway, Render, Cloud Run, Azure)wisp deploy init docker (Docker)
Static host (GitHub Pages, GitLab Pages, S3)wisp build --static (or --spa)
Edge or serverless (Cloudflare, Deno Deploy, Vercel, Netlify, Amplify, Firebase, Azure Static Web Apps)wisp build --target <host> (Edge and serverless targets)
AWS Lambda / Bun / Node--target lambda / --target bun / --target node

An app that signs cookies (sign-ins, signed cookies, tokens, OAuth) needs WISP_SECRET (32+ random characters, for example openssl rand -hex 32) on every host. A release server whose app signs does not start without it; if the build could not tell, the server logs once and refuses signed things until it is set. Logs and metrics: Observe. Per host: Hosting.

In a host's CI a plain wisp build picks the target from its variables and says so: WORKERS_CI (cloudflare), CF_PAGES (pages), VERCEL (output in .vercel/output), NETLIFY, DENO_DEPLOYMENT_ID (deno), AWS_APP_ID (node). --target native forces the binary.

wisp deploy init <host> writes a config:

HostWrites
cloudflare, cloudflare-pages, deno, vercel, netlify, lambda, pages (GitHub Pages).github/workflows/deploy.yml: build and deploy on push to main. Line 1 names the secrets; --force replaces it. cloudflare and cloudflare-pages also write a wrangler.toml when there is no Wrangler config (Your wrangler config)
fly, render, railway, cloud-runthat host's config, and a Dockerfile if none
dockera Dockerfile (--onion: Tor)
tortorrc and env for Tor (--unix: socket)

node and bun are servers for hosts that run npm start or a container.

Binary

wisp build makes one release binary with static files and styles inside. It listens on $HOST:$PORT (0.0.0.0:3000 in release).

The h2 feature serves h2c with prior knowledge on the same port (for a proxy that speaks h2c); WebSockets work over it. There is no TLS.

# Cargo.toml
wisp = { version = "..", features = ["h2"] }

Behind a reverse proxy: TLS, HTTP/2, HTTP/3

Wisp has no built-in HTTPS or ACME. Put Caddy or nginx in front; the proxy talks plain HTTP/1.1 to Wisp on the same machine. Bind Wisp to loopback so only the proxy reaches it, and tell it what the proxy tells the visitor:

HOST=127.0.0.1 PORT=3000 ORIGIN=https://example.com SITE_URL=https://example.com WISP_CLIENT_IP_HEADER=x-forwarded-for WISP_HSTS=on ./app

Wisp reads these headers from the proxy and no others:

HeaderUsed for
x-forwarded-protoHTTPS or not: Secure cookies, WISP_HSTS, absolute links when SITE_URL is unset. The last value counts (WISP_CLIENT_IP_DEPTH from the right), the one the proxy added. Believed only when WISP_CLIENT_IP_HEADER is set; cookies are Secure anyway except for plain http to localhost or loopback, so a plain-http deploy reached by another name needs a proxy that sends x-forwarded-proto: http (with WISP_CLIENT_IP_HEADER), else sign-in fails (logged once)
x-forwarded-hostthe host the visitor typed, for the form-post same-site check (with ORIGIN) and absolute links
the header named by WISP_CLIENT_IP_HEADERthe client address (cx.client_ip(), rate limits). The last address counts. Unset, the client is the proxy

There is no trusted-proxy list: only the proxy may reach Wisp (loopback, firewall or private network). ORIGIN is the address visitors type, with no path.

Caddy

Caddy gets a certificate itself and serves HTTP/2 and HTTP/3 (open UDP 443 too). It replaces any X-Forwarded-* the visitor sent; header_up adds X-Real-IP. Run the app with WISP_CLIENT_IP_HEADER=x-real-ip.

example.com {
    encode zstd gzip
    reverse_proxy 127.0.0.1:3000 {
        header_up X-Real-IP {remote_host}
    }
}

encode is optional; Wisp serves its embedded files as brotli (made at build time) or gzip, and gzips COMPRESS routes (Serve extras).

nginx

nginx needs the headers spelled out and a certificate. HTTP/3 needs nginx 1.25+ built with QUIC.

map $http_upgrade $connection_upgrade { default upgrade; '' close; }

server {
    listen 443 ssl;
    listen 443 quic reuseport;
    http2 on;
    server_name example.com;
    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
    add_header Alt-Svc 'h3=":443"; ma=86400' always;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_buffering off;
        proxy_read_timeout 1h;
    }
}

server {
    listen 80;
    server_name example.com;
    return 301 https://$host$request_uri;
}

proxy_buffering off lets streams and live updates through as written, Upgrade is for WebSockets, and proxy_read_timeout 1h keeps a quiet event stream open. Run the app with WISP_CLIENT_IP_HEADER=x-real-ip.

Unix socket

A proxy on the same machine can reach the app over a Unix-domain socket instead of a TCP port: run it with WISP_LISTEN=unix:/run/app/app.sock and point the proxy at the socket (nginx proxy_pass http://unix:/run/app/app.sock;, Caddy reverse_proxy unix//run/app/app.sock). It prints wisp: listening on unix:<path>, replaces a socket file left by an earlier run (nobody answers on it), refuses to replace a live server's socket or any other file, and removes its own socket on stop (a killed run leaves one, which the next start replaces). It serves HTTP/1.1 on tokio's driver on Linux and macOS, not the io_uring or epoll ones, and takes no WebSocket upgrades. A WebSocket upgrade logs WebSockets need a TCP listener, not WISP_LISTEN=unix: and closes the connection. Every peer reads as 0.0.0.0, so set WISP_CLIENT_IP_HEADER (here x-real-ip) or rate limits by client IP count all visitors as one. The socket is created with the process's umask, so under the usual 022 only its own user can connect: run the proxy as that user, or give both a group and start the app with umask 002 (systemd UMask=0002) in a directory the group can enter. server --health probes PORT and so does not see the socket; check it with curl --unix-socket /run/app/app.sock http://x/_wisp/health.

Static and SPA

wisp build --static [--out site] writes dist/, each parameterless page as about/index.html. Each head inlines the CSS rules its markup can match, and the whole minified sheet loads at the end of the body as a low-priority <link>. --spa and prerendered pages get the same. --static and PRERENDER skip a guarded page (SIGNED_IN or MIDDLEWARE on the page or a layout): a file has no guard. --static prints a warning. It skips a link to a guarded page, with no dead-link error. A guard you write in code (a before hook or a load that redirects) does not count: use SIGNED_IN or MIDDLEWARE. Under a CSP whose style-src (else default-src) lacks 'unsafe-inline' or has a nonce or hash, nothing is inlined.

The export also writes static/ and the /_app files (.maps with --sourcemap). Forms need a server, and the export warns for each page with actions or a posting form. A [params] route lists its pages in src/routes/blog/[slug]/+page.wisp (or its +page.rs):

---
fn entries() -> Vec<&'static str> {
    vec!["hello", "second-post"]
}
---
  • entries returns a String or &str per param, or a tuple in path order. An empty string leaves out an optional or rest param.
  • A route with actions or a +server.rs needs a server (the export warns).
  • dist/_headers (Netlify, Cloudflare Pages) holds the pages' security headers (the CSP, x-content-type-options, referrer-policy, and strict-transport-security when built with WISP_HSTS=on), the headers = [...] rules of Cargo.toml (/api/[id] becomes /api/:id, [...p] becomes *), and cache rules: versioned /_app/ files, /_app/img/* and /_app/c/npm/* are immutable for a year, while /_app/c/el/* and source maps revalidate.
  • Cloudflare Pages reads only the first 100 rules (not measured here). Past that, wisp build warns warn _headers: N versioned files past Cloudflare Pages' 100 rules keep the host's default cache. Your own static/_headers goes first and counts against the 100. Wisp does not write again a header your file sets on a pattern (one CSP, not two). A file whose Cache-Control your file or a headers rule sets gets none of the generated cache rules.
  • --static builds with WISP_STATIC=1. A plain cargo build --release leaves the exporter out and stops with a message under WISP_EXPORT; set WISP_STATIC=1 to run the export yourself. Run the binary from the app folder: WISP_EXPORT writes its file list in .wisp/ of the working directory.
  • --spa is --static plus an index.html fallback for routes the browser draws. It writes _redirects (Netlify, Cloudflare Pages), vercel.json rewrites and a 404.html shell (GitHub Pages), and keeps your own files (see Static Export).
  • A const SSR: bool = false; page whose [params] have no entries is written once to _app/spa/N.html. wisp.js draws the one whose route fits, so route.params and load({ params }) hold the address's params. Each page loads /_app/c/spa.js (about 1.7 KB gzipped), which prefetches those pages.

Speed

_headers caches each versioned /_app/ file for a year. Images get width/height and loading="lazy" (fetchpriority="high" and <img priority> skip the lazy). The router fetches a link's page ahead on hover, touch, press and keyboard focus. Release builds minify src/lib and component modules.

A stale-while-revalidate rule of your own can show a page one deploy old that names the old build's /_app/ files, so keep those reachable. Behind Cloudflare, turn off Rocket Loader, which breaks scripts on swapped-in pages.

cargo run -q -p wisp-gate site (in the Wisp repo, with this site at ../wisp-docs or WISP_DOCS_DIR) builds this site with wisp build --static; the full gate does too (fast skips it). The site checkout must be on main. A default ../wisp-docs on another branch fails the step. It prints the path, the HEAD and "set WISP_DOCS_DIR to the docs checkout on main". An explicit WISP_DOCS_DIR on another branch fails the audit and stamps steps. The speed budgets still run and print a line about the branch. The speed gate fails on a page over budget, a render-blocking <script src> in <head>, a dead file link, or an <img> without width and height. Budgets: HTML 20,365 B (21,200 B for the benchmarks page), critical CSS in the head 8,500 B (9,180 B for the examples pages and 9,650 B for the home page), linked CSS 30,500 B, scripts and module preloads 47,000 B, preloaded fonts 108,000 B. The HTML budget counts a changelog version page without its release body (the <article> element). The body has its own ceilings: 29,800 B and 11,450 B gzipped. The pages of the unreleased changes have the same ceilings. The consts at the top of tests/gate/src/site.rs in the Wisp repo set them. cargo run -q -p wisp-gate site --dist <folder> checks a site that is already built in <folder> against the same budgets. It builds nothing and needs no docs checkout.

Lighthouse is a hand check: npx --yes lighthouse@12.8.2 http://localhost:8080/docs/ --form-factor=mobile --only-categories=performance, median of three runs.

Prerender

---
const PRERENDER: bool = true;
// with [params]
fn entries() -> Vec<&'static str> {
    vec!["hello", "second-post"]
}
let post = db::post(&slug).await?;
---
  • wisp build builds the binary, runs it once (init runs) to render those pages, builds again with the bytes inside, and serves them as they are (ETag, 304).
  • One render serves all, so cx in statements, markup or load is a build error. Layouts render once, as for a request without cookies.
  • The crawl, as SvelteKit's prerender.crawl: the <a href>, <link href> (not resource hints) and <img src> of each prerendered page are followed (not inside comments, <script>, <style> or <template>), query and fragment dropped, other hosts and schemes left out. The app's router (matchers included) names the route of each link. A PRERENDER route renders the page and its links are followed in turn, so a [slug] route needs no entries() when a prerendered page links to its pages. A route that is not prerendered is the server's: not fetched. A static/ file or built asset is fetched and is fine. The crawl sends a GET to each page it follows, so a GET route that changes data runs at build time. At most 10000 pages. A PRERENDER route with parameters, no entries() and no page found gets a warning.
  • A link that answers 400 or more fails the build: error /blog links to /blog/gone, which answered 404, then N dead links. Fix them, or build with --allow-dead-links to only warn. wisp build --allow-dead-links (or WISP_DEAD_LINKS=warn) only warns.
  • A link with a fragment to a page that the build wrote must name an id of that page, or the name of an <a> there: error /blog links to /blog/hello#intro, but no element has the id intro. A fragment of the own page (#intro) counts too. #top and an empty fragment pass. The build does not check a link to a page that it did not write. The same flag and variable only warn. wisp build --no-crawl follows no link: then only the routes and entries() say which pages are rendered.
  • --static prerenders every page.
  • The build calls wisp::prerender on the app. You never call it yourself.

Service

wisp build, then wisp service install (as root or administrator). It copies the release binary to /usr/local/lib/<name>/ (%ProgramFiles%\<name>\ on Windows) and runs it in the app folder as a boot-time OS service. After a new wisp build, run install again. The other commands are start, stop, status and uninstall (which removes the copy).

wisp host builds the app as you, installs the service with sudo and keeps a list of the apps on the machine (Wisp Host).

OptionWhat it does
--user <name>run as that user (Windows: a limited task)
--rootrun as root (SYSTEM on Windows); install needs this or --user
--port <n>listen port
--name <service>service name (default: the package name)
--dry-runprint what would be written and run, change nothing
  • Linux: /etc/systemd/system/<name>.service with Restart=on-failure, EnvironmentFile=-/etc/<name>.env (made 0600 if missing; put WISP_SECRET there), LimitNOFILE=1048576, a sandbox (NoNewPrivileges, ProtectSystem=strict with the app folder as the one ReadWritePaths, PrivateTmp, UMask=0027 and more) and AmbientCapabilities=CAP_NET_BIND_SERVICE for --port below 1024. A WISP_DATA elsewhere needs its own ReadWritePaths line via systemctl edit <name>. The --user must be able to read the app folder.
  • macOS: /Library/LaunchDaemons/wisp.<name>.plist, loaded with launchctl.
  • Windows: a scheduled task at startup (schtasks). stop ends the process without draining.

SIGTERM and Ctrl+C make the runtime stop accepting and drain for up to WISP_DRAIN seconds (10). Server-sent events end cleanly at once; any other streamed body (Response::stream, ndjson) goes on in the drain window, and one the exit still cuts off ends without its last chunk, so the client sees it incomplete rather than a short 200. WISP_STOP_DELAY=5 first serves on for 5 s with /_wisp/health answering 503, so a load balancer moves traffic first. On Linux a systemd .socket unit can pass the listening socket (LISTEN_FDS).

Docker

wisp deploy init docker              # --force replaces existing files
docker build -t my-app .
docker run -p 3000:3000 -e WISP_SECRET=... my-app
  • It writes a Dockerfile and .dockerignore. The image builds on a pinned rust:1.98-slim-trixie (cargo-chef layer) and runs on distroless gcr.io/distroless/cc-debian13 as user 65532 (WISP_USER: the server gives /data to it and drops root itself). It sets HOST=0.0.0.0 and WISP_DATA=/data, has a HEALTHCHECK of server --health, and no VOLUME line (Railway refuses one).
  • Its build makes the server only; for a Lambda container image build with WISP_LAMBDA=1, or use wisp build --target lambda. .dockerignore keeps .env and .env.* out.
  • Saved tables live in /data; mount a volume (-v my-app-data:/data).
  • Docker's default seccomp refuses io_uring, so the server uses an epoll per worker; a profile allowing io_uring_setup, io_uring_enter and io_uring_register brings it back. The first stderr line says which the server uses. Each io_uring worker lends 28 receive buffers, and a quarter more (at least 16) when a receive finds none.

Reproducible builds

Two builds of one commit must give the same binary. These are the parts Wisp gives you:

  • Lock file. Commit Cargo.lock. wisp new does not ignore it. The Dockerfile builds with --locked, so a stale lock fails the build. wisp deploy init docker (and the hosts that write a Dockerfile) stops when Cargo.lock is missing. Run cargo generate-lockfile and commit the file. An app inside a Cargo workspace has its lock at the workspace root, and the Dockerfile copies only the app folder, so such an app must build outside the workspace. Use cargo build --release --locked for your own builds. The CI file of wisp deploy init installs the wisp CLI with --locked, at the release tag that Cargo.toml of the app pins (--tag v1.0.0-pre.3). It reads the tag of a Wisp dependency written on one line with package = "wisp-web (with spaces) and tag = "x" (with spaces). Else it uses the tag of the CLI that wrote the file. This holds for a multi-line [dependencies.wisp] table, for tag="x" with no spaces, for a dependency with no package key, and for a tag that is not a release version. wisp upgrade sets the --tag of that file to the new release.
  • Compiler. wisp new writes rust-toolchain.toml with the Rust version of the Docker image (channel = "1.98", rustfmt and clippy). Rustup installs that version for the app, so local builds and the image use one compiler. Change the file and the FROM line of the Dockerfile together. Wisp needs Rust 1.89 or newer.
  • Targets. A rustup target belongs to one toolchain. For an edge build (--target cloudflare, deno and the others) run rustup target add wasm32-unknown-unknown in the app folder, so rustup adds it to the pinned toolchain. The build error names this command.
  • Paths. App::ROOT is "." in a release build. A release build with the build cache (wisp build) remaps the cache folder to ./target and the workspace folder to a relative path. Any other release build remaps a path in the folder of the workspace to a relative path (also in compiler errors). Your RUSTFLAGS and cargo config apply as before. The binary then has no path of the app folder. Paths of path dependencies and of $CARGO_HOME and the Rust toolchain stay in it. This holds for an app with only a binary target and no [[bin]] or autobins. Other apps build plain: the path stays in the binary (with a library target: in the library, and with the cache it is the cache folder). The Docker image always builds in /app.
  • Image tools. The Dockerfile pins the Rust image and the cargo-chef version.
  • Time. Wisp writes no clock time in the bytes of the generated code or the static export. It does not read SOURCE_DATE_EPOCH, because it has no timestamp to set. A test generates the code twice and exports the test app twice, and checks that the bytes are the same.

An export (wisp build --static) empties the nonce="…" value of a tag and the token of the <form guard> input in the pages it writes. A static page has no visitor to bind them to, and a random value would change every file on each build. A guarded action refuses an empty token, so a guarded form needs a running Wisp server. If your app uses wisp::csp_nonce(), its exported pages have no nonce. The exported _headers use the hash policy, so an inline script that needs a nonce can fail there. Test the exported site with wisp preview --static.

Is This Page Useful?

View This Page's Source

Type to search every docs page and heading.