Hosting
Wisp builds one binary for a server and an image for a container host. It builds plain files for a static host and WebAssembly for an edge or serverless host. Each host page has the build command, deploy steps, environment and limits. For general rules, see Deploying and Edge and serverless targets.
Wisp Host
On a server or a PC that you control, wisp host sets up the app and keeps it running. On Linux and macOS, run it as your own user and give it the app folder (the default is the current folder):
wisp host /srv/my-app
It asks its questions, checks for Caddy and builds the app as you. Then it shows "This needs administrator rights. Wisp runs sudo." and runs sudo -- env WISP_HOST_ELEVATED=1 <wisp> host ... with each answer as an option. sudo asks for your password. The run under sudo asks nothing and never runs cargo build. Your account needs sudo rights for that command. A sudoers rule for one wisp path only does not match it.
update, delete, start, stop and restart of a native app run sudo the same way. So does status on macOS. On Linux, delete of an app behind Caddy also runs sudo. So does update of such an app when its Caddy block is missing. delete asks you first, before sudo. logs, and status on Linux, never need sudo. Not checked: logs for a user who is not in the adm or systemd-journal group. It may show no lines. Before it runs sudo, Wisp checks that the run under sudo sees the same list and build. Else it stops with an error (see Errors). An app in a cargo workspace builds into the target folder of the workspace, so Wisp may refuse it.
wisp host never runs cargo build as an administrator. A docker image build is different: as root or under sudo, compose up -d --build builds the image as root. A docker app behind Caddy on Linux runs sudo for its add, and for an update when the Caddy block is missing. On Windows, with --dry-run, or with no sudo on PATH, it does not run sudo. Then build the app first, and run wisp host as an administrator (an administrator terminal on Windows). Not checked: that sudo wisp finds wisp in the secure_path of sudo. The commands:
wisp build
sudo wisp host /srv/my-app
It reads the machine: the OS, the CPUs, the RAM, the free disk, docker or podman, Caddy, a package manager and ports 80 and 443. Then it asks for the domain, the method, the proxy and the account when no option gives them. It asks for the method only when docker --version or podman --version runs. It asks for the proxy only with a domain, and for the account only for native. The name, the port and --install-deps take their defaults. It picks a setup that fits and installs it. wisp host info shows the facts, the setup that it picks and the list folder that an add writes. It changes nothing. --dry-run shows each command and file, and changes nothing. For a user whose real run uses sudo, it shows the system list folder. wisp host help (also --help and -h) shows the rows of wisp host.
With no terminal, a missing answer is an error that names its option. --yes (-y) takes the defaults: no domain, native, Caddy for a domain, and the account in SUDO_USER, USER or USERNAME. That account is never root: with SUDO_USER=root, Wisp uses USER or USERNAME. So for a native app, root with no SUDO_USER and --yes must give --user or --root.
| Option | What it does |
|---|---|
--name <s> | the name of the app in the list. The default is the package name in lowercase, with - for _. A name is 1 to 40 of a-z, 0-9 and -, with a letter or digit first. Wisp refuses the words of wisp host, and caddy, docker, ssh, sshd, nginx, apache2, httpd, tor and systemd |
--domain <d> | the domain of the app. Caddy then runs in front of the app for HTTPS, because the Wisp server has no TLS. Wisp refuses the domain of another hosted app |
--no-domain | no domain: the app serves plain HTTP on its port. It is the answer to the domain question when there is no terminal |
--port <n> | the port of the app. Wisp refuses the port of another hosted app, and the error names that app. An app behind Caddy also takes ports 80 and 443. With no --port, an administrator with no domain gets 80 when port 80 is free and no hosted app takes it. Else the app gets the first port from 3000 that no hosted app takes and no program holds. Behind Caddy, the port cannot be 80 or 443. The check of a free port binds 127.0.0.1 only, so a program on another address can hold the port. A user who is not root never gets port 80, also when the run goes through sudo |
--method native|docker | native is the default. It runs the release binary as a system service, as wisp service does: a systemd unit, a launchd daemon or a Windows scheduled task. docker runs the app with docker compose or podman compose. Wisp asks this question only when docker --version or podman --version runs. It does not check that the daemon runs |
--proxy caddy|none | what is in front of a domain. caddy is the default for a domain and needs --domain. none serves plain HTTP on the port. With a domain, it warns |
--user <u>, --root | the account that runs the native service. The service runs as root only with --root (SYSTEM on Windows) |
--yes, -y | ask nothing. Use the defaults |
--install-deps | install Caddy when the setup needs it and it is missing. It runs apt-get, dnf, pacman, brew or winget. Without it, wisp host stops and shows the command. Wisp never installs Docker |
The native setup and Caddy on Linux need an administrator (sudo on Linux and macOS). A program folder that Wisp creates for the service gets mode 755. A program folder of Wisp that exists must be owned by root, and no group or other user can write it. A native app cannot take the name of a service that Wisp did not make. These are such services: a systemd unit (in systemd/system under /etc, /run, /usr/local/lib, /usr/lib or /lib) or a launchd plist that is outside /etc/ and /Library/. Wisp reads no text of such a file. A unit or plist in /etc/ or /Library/ without "(Wisp app)" in it is also such a service. A scheduled task that does not run the Wisp program folder, or a program folder without .wisp-service, is also such a service.
wisp host warns when the disk of the host files has less than 2 GiB free. When the machine has less than 2 GiB of RAM and the app has no release build, it warns: "RAM is below 2 GiB. A release build may need more." A native build then runs with CARGO_BUILD_JOBS=1. A run that goes through sudo never shows this warning: it builds, then runs sudo, and only the run under sudo shows warnings. For docker, the warning adds: "The image build runs cargo with the default jobs of cargo." With no proxy, it warns when the app port is 80 or 443 and a program uses it. When Caddy is not installed yet and a program uses port 80 or 443, it warns too: Caddy needs both ports.
With a domain and Caddy, the app gets ORIGIN and SITE_URL (https://<domain>) and WISP_CLIENT_IP_HEADER=x-real-ip. A native app also gets HOST=127.0.0.1. A container publishes its port on 127.0.0.1 only. On Linux, the Caddy block is /etc/caddy/conf.d/<name>.caddy. wisp host adds import /etc/caddy/conf.d/*.caddy to /etc/caddy/Caddyfile when no import of the blocks is there, then runs systemctl reload caddy. An import of conf.d/* or conf.d/*.caddy, as an absolute or a relative path, counts. A second run never adds a second import line. Wisp writes the new Caddyfile to a temporary file, then renames it. The file keeps its mode, and its owner is the user of the run (root under sudo). On macOS and Windows, it writes a Caddyfile in the host folder and tells you the line to add: import "<path>".
The docker setup needs a Cargo.lock. It writes Dockerfile, Dockerfile.dockerignore, compose.yml and app.env (kept when it exists) in the host folder. Then it runs docker compose -p wisp-<name> -f <host folder>/compose.yml up -d --build.
The list gets the app as soon as the app runs, before the Caddy step. When the Caddy step fails, run wisp host delete <name> to undo. Or fix the cause and run wisp host <name> again: the update writes a Caddy block that is missing. An update never overwrites a Caddy block that exists. An add fails when the file of its Caddy block exists (see Errors). On Linux, a user who is not root runs sudo to write the block. With no sudo on PATH, or with --dry-run, that user gets a warning, and the block stays missing.
Put WISP_SECRET in /etc/<name>.env (native on Linux) or in app.env (docker). Then run wisp host restart <name>. After a native add on macOS or Windows, Wisp shows no file for WISP_SECRET. Not checked: that restart of a docker app reads app.env again.
The List
The folder of the host files is:
WISP_HOME, if you set it.- Else, for an administrator:
/var/lib/wisp(%ProgramData%\wispon Windows). - Else:
~/.wisp. Such a user also reads the list of the system folder.
hosts.tsv in that folder holds one line for each app: name, path, method, port, domain, proxy and the install date. A change of the list keeps each comment and each other line byte for byte. The host folder of an app is hosts/<name> in that folder. Each time Wisp sets up a host folder, it writes a .wisp-host file in it, also when the folder exists.
| Command | What it does |
|---|---|
wisp host <name> | update an app of the list, as wisp host update <name> does. With --name, --domain, --port, --method or --proxy it is an error: an update keeps the setup. With --user, --root, --no-domain, --install-deps or --yes, it is an update, and Wisp ignores these options |
wisp host update <name> [--dry-run] | native: an administrator uses the release build that exists, and fails without one. Another user runs wisp build, with CARGO_BUILD_JOBS=1 below 2 GiB of RAM. It checks the program folder before it stops the service. Then it stops the service, copies the new binary and starts it. When the copy fails, it starts the old binary again. The service files stay. docker: compose up -d --build. Behind Caddy, it writes the Caddy block only when it is missing. It needs the app folder |
wisp host list | each app with its method, port, domain, state and path |
wisp host status|start|stop|restart <name> | the state of the app, or start, stop or restart it. These commands work when the app folder is gone. Not checked for docker |
wisp host logs <name> [-n <lines>] | the last lines of the log (100). Native on Linux reads journalctl. docker reads compose logs. A native service on macOS or Windows keeps no log |
wisp host delete <name> [--yes] [--purge] [--dry-run] | delete the service, or run compose down, which deletes the containers. Then delete the Caddy block. On Linux it reloads Caddy when Caddy runs. On macOS and Windows it tells you to delete the import line from your Caddyfile. It deletes the line in the list last. The app folder stays, and delete works when the app folder is gone |
--purge also deletes the container volume, /etc/<name>.env (native on Linux) and the host folder. Without --purge, /etc/<name>.env stays. It deletes a host folder only when the folder has the .wisp-host file. delete asks first, unless you give --yes or --dry-run. A step has no work when its thing is not there. With a compose.yml but no docker or podman, it warns, skips compose down and goes on. When a step fails, the list keeps the line: run delete again. A program folder that holds files that Wisp did not write stays, with a warning. Then Wisp refuses that name until you delete the folder by hand.
delete keeps the line import /etc/caddy/conf.d/*.caddy in /etc/caddy/Caddyfile, because other apps can use it. Not checked: that Caddy takes the file with that line and no blocks.
Security: a root update installs the build from the app folder, which your user owns. Wisp trusts that build at the install. The program folder that only an administrator can write protects it only after the copy.
Limit: the list has no lock. Two wisp host runs at the same time can lose a line of the list. Run one at a time.
Errors
| Message, first line | Second line | Kind |
|---|---|---|
<exe> is not built. wisp host does not build as an administrator. | Run wisp build as your own user, then run this again. | error |
The variable WISP_HOST_ELEVATED has a value, and you are not an administrator. | Run wisp host as root. | error |
sudo drops WISP_HOME, so the run under sudo would use another list. | Run wisp host as root with WISP_HOME set, or unset WISP_HOME. | error |
The path of wisp has = in it. sudo env reads it as a variable. | Move wisp to another folder. | error |
The path of wisp has a line break in it. | Move wisp to another folder. | error |
The list of this app is in <base>. The run under sudo reads only <system>. | Run wisp host as the user that hosted the app, or as root with WISP_HOME=<base>. | error |
The build is <a>, and the run under sudo looks for <b>. | A custom target folder is not seen under sudo. Run wisp build, then run wisp host as root with the same settings. | error |
<s> is not a host name. | Use 1 to 40 of a-z, 0-9 and -, with a letter or digit first. Set one with --name. | error |
No port from 3000 to 65535 is free. | Set one with --port. | error |
<name> is the name of a program folder that Wisp did not make: <dir> holds files that Wisp did not write. | Delete the folder by hand, or set another name with --name. | error |
<dir> holds files that Wisp did not write, so Wisp does not replace the program in it. | Delete the folder by hand, then host the app again. | error |
<dir> is not owned by root, or another user can write it. A service runs the program in it. | Run chown root and chmod 755 on it, or delete the folder. | error |
<file> exists, and no app in the list has it. Wisp does not write over it. | Delete the file, or use another name with --name. | error |
<path> is a symbolic link. Wisp does not delete through a link. | Delete the host folder by hand. | error |
Wisp has an empty command to run. This is a bug in Wisp. | (none) | error |
<file> is missing, and only root can write it. | Run wisp host update <name> with sudo to write it. | warning |
<dir> stays, because it holds files that Wisp did not write. Delete it by hand to host a service with this name again. | (none) | warning |
Line <n> of <path of hosts.tsv> has 7 fields but is not an entry. Wisp skips it and keeps it as it is. | (none) | warning |
A run checked these on Ubuntu 24.04 (WSL, systemd), as a user with sudo and no password. The list: add, list, status, logs, stop, start, restart, update, delete, Caddy and the sudo step. Not checked yet: macOS, Windows, Docker, Podman, the password prompt of sudo, --purge and the Caddy block under sudo.
All commands and options: CLI.
All Hosts
| Host | Build command | Runtime |
|---|---|---|
| VPS | wisp host or wisp build | native binary or container |
| Docker | wisp deploy init docker | container |
| Fly.io | wisp deploy init fly | container |
| Render | wisp deploy init render | container |
| Railway | wisp deploy init railway | container |
| Cloudflare | wisp build --target cloudflare or pages, in CI wisp deploy init cloudflare or cloudflare-pages | WebAssembly on Workers or Pages |
| Deno Deploy | wisp build --target deno, in CI wisp deploy init deno | WebAssembly on Deno (Classic closed 20 July 2026. The new Deno Deploy closes about six months after 9 October 2026) |
| Vercel | wisp build --target vercel, in CI wisp deploy init vercel | WebAssembly, Node function or Edge |
| Netlify | wisp build --target netlify, in CI wisp deploy init netlify | WebAssembly, function or edge function |
| AWS Lambda | wisp build --target lambda, in CI wisp deploy init lambda | static Linux binary |
| Bun | wisp build --target bun | WebAssembly on Bun |
| Node | wisp build --target node | WebAssembly on Node 20+ |
| Tor onion service | wisp deploy init tor, wisp deploy init docker --onion or wisp build | container or native binary behind Tor |
| GitHub Pages | wisp build --static, in CI wisp deploy init pages | static files |
| Cloud Run | wisp deploy init cloud-run | container |
| Azure | wisp deploy init docker or --target node | container or WebAssembly on Node |
An app that signs cookies needs WISP_SECRET (32 or more random characters) on every host. See Environment variables.
Is This Page Useful?