Environment Variables
Wisp reads these once at start. An empty value counts as unset. A non-empty invalid value stops the server with a message. Switches take on/off (also 1/0, true/false, yes/no).
Browser code reads PUBLIC_* variables as env.PUBLIC_X, filled in at build. With public_env = true in [package.metadata.wisp], import { env } from 'wisp' reads them as the server saw them at its start (Config). A prerendered page (PRERENDER) that the server sends holds the server's values from its start. A static page that the build bakes (a page with no Rust) holds them too. wisp build --static runs the server on the build machine, so the exported pages hold that machine's values. A PUBLIC_ name with SECRET, PASSWORD, PASSWD, PRIVATE or CREDENTIAL in it is an error: the build refuses it, and with public_env = true the server does not start. A PUBLIC_ name must use only A-Z, a-z, 0-9 and _: a look-alike letter of another script is an error too. wisp check --types types env with one readonly member per PUBLIC_* variable that the build reads.
A variable comes from the process first. Then Wisp reads these files in the app folder. A later file wins: .env, then .env.development (dev mode, WISP_DEV) or .env.production (other modes), then .env.local, then .env.development.local or .env.production.local. A file that does not exist adds nothing. Wisp reads the files once, at start. The build reads the files of its profile (release reads production) for the baked PUBLIC_* values, and the server picks its mode from WISP_DEV at start. Set WISP_DEV in the process or in .env: the mode files cannot choose the mode. The last WISP_DEV line of .env wins. Wisp ignores WISP_DEV in a mode file and logs a line, so wisp::env("WISP_DEV") reads the value that chose the mode. The mode follows the build profile: a debug build (as under wisp dev) reads development and a release build reads production, unless WISP_DEV says otherwise. Cargo does not see a mode file that you create after the first build. Run cargo clean -p <app> and then wisp build again, or touch build.rs. Keep the .local files out of git (wisp new ignores .env.*).
A few variables come from the process only, and Wisp does not read .env for them. systemd sets LISTEN_FDS and LISTEN_PID. Lambda sets AWS_LAMBDA_RUNTIME_API. It chooses the Lambda mode and the folder of the saved tables, kv and blobs. A WebSocket send from Lambda reads AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN and AWS_ENDPOINT_URL_APIGATEWAYMANAGEMENTAPI. The dev error dialog reads WISP_EDITOR and EDITOR. The front of wisp dev reads HOST and WISP_DRAIN.
For your own variables use wisp::env("KEY"), wisp::env_or("KEY", 4) or #[derive(Config)]. Call Conf::get() after the app starts, or Conf::load()? first in a test or another binary, because get() panics on bad variables.
Server
| Name | What it does |
|---|---|
HOST, PORT | listen address (0.0.0.0:3000 in release, 127.0.0.1 in dev) |
ORIGIN | the site's address as browsers see it, for a proxy that does not pass Host. A .onion address turns WISP_ONION on |
WISP_DEV | dev mode: on in debug builds. A release binary with WISP_DEV reads static/ and .wisp/ in its working directory, so run it from the app folder |
WISP_THREADS | worker threads, one per CPU |
WISP_LISTEN | unix:<path>: listen on that Unix-domain socket instead of HOST/PORT, for a proxy on the same machine (Deploy). Linux and macOS, on tokio's driver (not io_uring or epoll). A stale socket file there is replaced; a live server's socket and any other file are an error, and the file is removed on stop. A WebSocket upgrade gets the 101, then the server logs wisp: WebSocket on "<path>" refused: WebSockets need a TCP listener, not WISP_LISTEN=unix: and closes the connection. Wisp reads it like the other variables here: from the process, else from .env. Any other value stops the server |
WISP_IO | Linux: epoll instead of io_uring; uring fails at start where it cannot run |
WISP_MAX_CONNS | open connections before a 503 (unset: on Linux the open-file limit less 1024, within a quarter of memory at 16 KiB each; 10000 elsewhere; 0 no cap) |
WISP_BODY_LIMIT | largest request body (512KB, 10MB; 1 MB). const BODY_LIMIT sets it per route |
WISP_UPLOAD_LIMIT | most a request's Upload files may take in all (100 MB) |
WISP_SPOOL_LIMIT | most all requests together may stream to upload temp files at once, process-wide (default: 16× WISP_UPLOAD_LIMIT). Over it, a new file part is refused 503 until space frees; 0 no cap |
WISP_HANDLER_TIMEOUT | handler timeout in seconds (not for a WebSocket handler: WISP_WS_IDLE closes a quiet client while the handler waits in recv, and a handler that does not read must stop on Gone) |
WISP_WS_IDLE | seconds a quiet WebSocket lives (60, 0 never, at most 100 years) |
WISP_SSE_HEARTBEAT | seconds between : comment lines on a quiet Response::events stream (25, 0 none, at most 100 years) |
WISP_DRAIN | seconds a stopping server waits for requests under way (10, at most 100 years) |
WISP_STOP_DELAY | seconds between SIGTERM and closing the listener, while /_wisp/health answers 503 (0, at most 100 years) |
WISP_USER | uid or uid:gid: started as root, give WISP_DATA to that user and run as them. If the server cannot read its own user id in /proc/self/status, or cannot start itself as that user, it stops and does not run as root. Only Linux supports it: on another system a server with WISP_USER set stops |
LISTEN_FDS | Linux systemd socket activation: with LISTEN_PID this process, serve on the socket at descriptor 3 instead of binding PORT |
LISTEN_PID | the process LISTEN_FDS is meant for, set by systemd |
WISP_CLIENT_IP_DEPTH | which entry of WISP_CLIENT_IP_HEADER (and of x-forwarded-proto, x-forwarded-host), counted from the right, is the client's (1). Use 2 behind Render or Cloud Run |
WISP_CLIENT_IP_HEADER | header with the client address behind a proxy. The last address of the header's last line counts, the one the trusted proxy added; a client can forge the first. Setting it also makes x-forwarded-proto: http believed (plain cookies); unset, cookies are Secure except in dev and for plain http to localhost or loopback. wisp deploy init sets it where the host's header is safe |
WISP_LAMBDA_STREAM | 1 on AWS Lambda with a Function URL in RESPONSE_STREAM mode (Streaming) |
WISP_SECURE_HEADERS | off leaves out nosniff and referrer-policy |
WISP_REFERRER | the referrer-policy pages get (default strict-origin-when-cross-origin) |
WISP_HSTS | on adds strict-transport-security, not on plain http requests |
WISP_ONION | on: serve as a Tor onion service. Automatic for a .onion ORIGIN or SITE_URL; off turns it off; auto counts only requests to a .onion host. See Tor onion services |
WISP_PLUGIN | set by the build for the command of a build plugin: the plugin's name. The command reads it. The server ignores it |
WISP_PLUGIN_FILE | set by the build for the command of a build plugin: the path of the input file, relative to the app's root |
WISP_ONION_LOCATION | an onion address: clearnet pages answer with onion-location: http://….onion/<path> |
WISP_SERVER_TIMING | Server-Timing header (on in dev, not in the edge build). Only an answer that a route handler or its error page made has the header. An early upload refusal (a 429 or the sign-in answer) has none. |
WISP_PROBLEM_JSON | on: errors as RFC 9457 problem JSON |
WISP_REQUEST_ID | on: every request gets an id (cx.request_id()), echoed as x-request-id |
WISP_ALLOWED_HOSTS | comma-separated Host values (127.0.0.1:1420,localhost:1420, with the port the browser sends; on 80 or 443 list it without the port, as browsers leave it out). A request with another Host, or with none (HTTP/1.0), is a 421 (Misdirected Request), so a page on another name pointed at this address (DNS rebinding) cannot read the app. Unset: any host, and nothing is checked. Not derived from ORIGIN, since a proxy may rewrite Host. It holds on the native server and on the node, deno, bun and cloudflare targets. On cloudflare, the files of static/ come from Cloudflare and skip the check. The pages, vercel, netlify and azure hosts also serve those files before the app. Not tested on those hosts. wisp::allow_hosts (native only) sets it from code (Deploy targets) |
WISP_API_DOCS | serve /_wisp/openapi.json and /_wisp/docs (on in dev; no docs page on Cloudflare, Pages, Vercel, Netlify) |
WISP_SECRET, WISP_SECRET_OLD | key for signed cookies and tokens, and the one before (rotation). Unset outside dev, an app that signs does not start (openssl rand -hex 32) |
WISP_DATA | folder for table files and the kv and blobs stores in storage/ (off, in any ASCII case: in memory) |
WISP_FSYNC | second (default), always, off |
WISP_STORE | a store for tables: d1:DB, deno-kv, libsql://… |
WISP_KV_<NAME> | driver of wisp::kv("NAME"): cf:BINDING, deno-kv[:path], netlify-blobs[:store], fs[:dir], memory, upstash[:url]. Unset: the host's own store. See Storage |
WISP_BLOB_<NAME> | the same for wisp::blobs("NAME"), plus s3:<endpoint>/<bucket> and vercel-blob[:private] |
WISP_SQL_<NAME> | database of wisp::sql("NAME"): libsql://<host>, https://<host> (Turso), http://<host>, d1-http:<account>/<database>. Unset: the D1 binding on Cloudflare, else 501 |
WISP_KV_<NAME>_TOKEN, WISP_SQL_<NAME>_TOKEN, WISP_BLOB_<NAME>_TOKEN | the token for that store's driver |
WISP_BLOB_<NAME>_KEY_ID, WISP_BLOB_<NAME>_SECRET, WISP_BLOB_<NAME>_REGION, WISP_BLOB_<NAME>_SESSION_TOKEN | the s3: driver's credentials (else AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION, AWS_SESSION_TOKEN) |
UPSTASH_REDIS_REST_URL, UPSTASH_REDIS_REST_TOKEN, KV_REST_API_URL, KV_REST_API_TOKEN | REST address and token for upstash |
BLOB_READ_WRITE_TOKEN, VERCEL_BLOB_API_URL | token and API address for vercel-blob |
CLOUDFLARE_API_TOKEN | token for d1-http: when WISP_SQL_<NAME>_TOKEN is unset |
NETLIFY_BLOBS_CONTEXT | set by Netlify, for netlify-blobs |
WISP_STORE_TOKEN | bearer token for a libsql:// store |
WISP_STORE_POLL | seconds between store change polls (several servers) |
WISP_BASE | base path, set at build (/app); same as base in [package.metadata.wisp] |
WISP_ASSET_BASE | where built /_app/ files are linked from, set at build (https://cdn.example.com or /static, with no ?, #, ;, ,, quote or space). A cross-origin host is added to script-src and style-src of the default CSP |
SITE_URL | site address for sitemaps, feeds and absolute links (also read from the .env files). Without it, only dev mode takes the request's Host. A release build then serves no /sitemap.xml, /robots.txt or /feed.xml, and wisp::alternates gives nothing. An edge build always uses SITE_URL alone, so set it on the edge host. |
SITE_TITLE | feed title |
METRICS_KEY | bearer key for /_wisp/metrics |
CRON_SECRET | bearer key hosts send to /_wisp/cron/<schedule> |
WISP_SERVE | 1: Node's server.mjs listens even when a launcher imports it (PM2 cluster, symlinked path) |
WISP_EXIT_ON_STDIN_END | 1: Node, Bun and Deno servers exit when stdin closes (wisp dev --target sets it) |
WISP_NODE_HTTP | 1: Node, Bun and Deno targets use the runtime's own HTTP server |
WISP_KEEP_ALIVE_TIMEOUT | Node, Bun and Deno targets: seconds a quiet kept-alive connection lives. The default is 65, also for a value that is not a number above 0. Bun.serve takes at most 255. |
AWS_LAMBDA_RUNTIME_API | set by Lambda; the wisp build --target lambda binary answers its runtime API |
AWS_ENDPOINT_URL_APIGATEWAYMANAGEMENTAPI | where a Lambda's WebSocket sends go (a VPC endpoint, LocalStack, a test) |
WISP_EDITOR, EDITOR | what the dev error dialog's Open runs (code -g) |
#[derive(Rest)] bearer tokens and OAuth client ids and secrets are read from the names their attributes give.
Set by the CLI and Hosts
You do not set these.
| Name | What it does |
|---|---|
WISP_NONCE | 0 while wisp build builds wasm for an app with no wisp::csp_nonce(, leaving the nonce code out |
WISP_HOST_ELEVATED | 1 in the run of wisp host under sudo. That run asks nothing and never builds. If it is still not an administrator, it stops |
WISP_REQUEST_ONLY | 1 for Cloudflare, Pages, Vercel or Netlify builds: leaves the raw-connection server loop out of the wasm |
WISP_EXTENSION | 1 at build for wisp build --target extension: Wisp's own files go under /wisp/, and the export follows the rules of an extension build |
WISP_APP_DIR | set by the build script of wisp-web-shared: the folder of Wisp's own files, _app, or wisp when WISP_EXTENSION=1 |
WISP_JS_FILE | set by the build script of wisp-web-rt: the path of wisp.js in that folder (/_app/wisp.js or /wisp/wisp.js) |
LIVE_JS_FILE | set by the build script of wisp-web-rt: the path of live.js in that folder (/_app/live.js or /wisp/live.js) |
WISP_LITS | 1 in wisp dev cargo builds: string, number and bool literals are read from a table so a literal-only save swaps in with no compile (see Literal Swap) |
WISP_WARM_UP | the Cloudflare worker's warm-up instance (WISP_WARM_UP=1) |
WISP_NONCE=0: 6,747 bytes (about 6.7 KB) smaller for wisp-test-app (2,527,786 bytes without it, 2,521,039 with it, Windows host, bench/edge/README.md).
Logs and Traces
| Name | What it does |
|---|---|
WISP_LOG | json: a JSON line per request with a severity |
OTEL_EXPORTER_OTLP_ENDPOINT | OTLP/HTTP traces to <endpoint>/v1/traces |
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT | the traces URL, as is |
OTEL_EXPORTER_OTLP_HEADERS | api-key=…,x=… |
OTEL_EXPORTER_OTLP_TRACES_HEADERS | the same, for traces only (wins) |
OTEL_SERVICE_NAME | service name on spans |
OTEL_BSP_SCHEDULE_DELAY | batch delay in ms (5000, at least 1) |
CLI and Tests
| Name | What it does |
|---|---|
SSL_CERT_FILE | wisp dev only: a PEM file of extra root certificates for the https:// targets of [package.metadata.wisp.dev.proxy], such as a local server with its own certificate (.wisp/dev-cert.pem of another wisp dev --https) |
WISP_DEV_ORIGIN | extra origins, comma-separated (https://app.test:5173). The wisp dev front serves a Host that is an IP address, localhost, a *.localhost name or the host of one of these origins. Each other Host gets a 403. These origins can also read the event stream of wisp dev (Security) |
WISP_STATIC | 1 at build: keep the static export (WISP_EXPORT). wisp build --static sets it. A release build with no PRERENDER page leaves the prerenderer out, and WISP_PRERENDER then writes nothing |
WISP_LAMBDA | 1 at build: keep the AWS Lambda runtime. wisp build --target lambda sets it |
WISP_DEAD_LINKS | warn: wisp build (its prerender crawl) and wisp build --static only warn of dead links and missing #ids, like --allow-dead-links (Edge and serverless targets) |
WISP_NO_CRAWL | 1: wisp build (its prerender) and wisp build --static follow no link, like --no-crawl |
WISP_NO_UPDATE_CHECK | any non-empty value but 0 silences the CLI-older-than-app warning, the daily newer-release lookup and the changes it lists. CI set to any non-empty value but 0 or false does the same for the lookup |
WISP_RELEASES_URL | the https release list URL that wisp upgrade, wisp changelog and the newer-release lookup read (default: the Forgejo API at code.wispweb.dev). Forgejo or GitHub releases JSON |
WISP_HOME | the folder of the wisp host files: its list hosts.tsv and one host folder for each app. Unset: /var/lib/wisp for an administrator (%ProgramData%\wisp on Windows), else ~/.wisp. See Wisp Host |
WISP_PORT_TRIES | how many next ports the app tries when another program holds its port (not set: none). wisp dev sets it to 0 for its app. The wisp dev front tries the next 20 ports |
WISP_DEV_CARGO | any value: wisp dev builds with cargo, never rustc directly |
WISP_BUILD_CACHE | 0: off. A path: where the build cache lives. By default wisp build, dev, test and new share one cargo build dir (%LOCALAPPDATA%\wisp\build, ~/Library/Caches/wisp/build, ~/.cache/wisp/build), so a second app reuses compiled dependencies. Skipped when CARGO_TARGET_DIR, CARGO_BUILD_TARGET_DIR, CARGO_BUILD_BUILD_DIR or a cargo config target-dir/build-dir is set. On E0463, E0786, E0460, E0514 or LNK1207 it cleans that package and retries once. wisp clean --cache empties it |
WISP_DEV_DIRECT | wisp dev builds .rs and .wisp saves with rustc directly. This is on by default on Windows (no proof) and Linux (each recording is proven first). On macOS it is off unless WISP_DEV_DIRECT=1 (experimental). 1 also skips the proof on Linux. WISP_DEV_CARGO turns it off everywhere |
WISP_DEV_PORT | set by wisp dev for [package.metadata.wisp.dev] run commands: the port it serves on (Config) |
WISP_CWEBP | the cwebp wisp build uses for images |
WISP_SASS | the Dart Sass for src/app.scss |
WISP_TSC | the tsc for wisp check --types |
WISP_BROWSER | Chrome or Edge for browser tests |
NO_COLOR | plain CLI output |
Is This Page Useful?