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

Wisp

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.

OptionWhat 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-domainno 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|dockernative 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|nonewhat 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>, --rootthe account that runs the native service. The service runs as root only with --root (SYSTEM on Windows)
--yes, -yask nothing. Use the defaults
--install-depsinstall 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%\wisp on 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.

CommandWhat 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 listeach 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 lineSecond lineKind
<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

HostBuild commandRuntime
VPSwisp host or wisp buildnative binary or container
Dockerwisp deploy init dockercontainer
Fly.iowisp deploy init flycontainer
Renderwisp deploy init rendercontainer
Railwaywisp deploy init railwaycontainer
Cloudflarewisp build --target cloudflare or pages, in CI wisp deploy init cloudflare or cloudflare-pagesWebAssembly on Workers or Pages
Deno Deploywisp build --target deno, in CI wisp deploy init denoWebAssembly on Deno (Classic closed 20 July 2026. The new Deno Deploy closes about six months after 9 October 2026)
Vercelwisp build --target vercel, in CI wisp deploy init vercelWebAssembly, Node function or Edge
Netlifywisp build --target netlify, in CI wisp deploy init netlifyWebAssembly, function or edge function
AWS Lambdawisp build --target lambda, in CI wisp deploy init lambdastatic Linux binary
Bunwisp build --target bunWebAssembly on Bun
Nodewisp build --target nodeWebAssembly on Node 20+
Tor onion servicewisp deploy init tor, wisp deploy init docker --onion or wisp buildcontainer or native binary behind Tor
GitHub Pageswisp build --static, in CI wisp deploy init pagesstatic files
Cloud Runwisp deploy init cloud-runcontainer
Azurewisp deploy init docker or --target nodecontainer 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?

View This Page's Source

Type to search every docs page and heading.