Skip to main content


At the end of the day, Wave produces web-apps with their own web server. This means any VM provider can be used for Wave deployment.

Deploying Wave scripts

Wave scripts are regular Python scripts. Deploy them as you would any Python script.

Deploying Wave apps

Wave uses 2 separate servers under the hood - waved (Go server) and wave app (Python server). See architecture to learn more.

Wave apps are ASGI-compatible, based on Uvicorn / Starlette, a high-performance Python server.

You can run Wave apps behind any ASGI server, like uvicorn, gunicorn, daphne, hypercorn, etc.

It's highly recommended to run Wave server (waved) separately from Wave app for production deployment in order to achieve the highest flexibility (custom ASGI server configuration). However, if you don't need that, you are good to go with a simple wave run --no-reload app.

To run your app using an ASGI server, append :main to the app argument. For example, if you were normally executing your app using wave run foo, and want to run your app using Uvicorn, use uvicorn foo:main.

These commands are equivalent:

(venv) $ wave run --no-reload --no-autostart foo
(venv) $ uvicorn foo:main

For more information, see and

To configure a different port, see configuring ports.


uvicorn accepts --env-file flag to specify .env configuration file for the Wave app. Note that as of time of writing, --env-file does not support configuration of Uvicorn itself. Using this flag may require running pip install python-dotenv first.

More info about various configuration options can be found in the configuration section.

Beyond defaults

If different than default ports are used for Wave server (http://localhost:10101) or Wave app (http://localhost:8000), it's necessary to properly set env variables:

  • Wave server - H2O_WAVE_LISTEN.

Deploying with HTTPS

Wave consists of 2 servers and both need to be configured separately.

  • Wave server - H2O_WAVE_TLS_CERT_FILE and H2O_WAVE_TLS_KEY_FILE environment variables.
  • Wave app - uvicorn foo:main <other-params> --ssl-keyfile=<key file> --ssl-certfile=<cert file>. See uvicorn docs.

HTTPS is all or nothing meaning either both server and app use TLS or none does.

Once set, the Wave app needs to know it should talk to the Wave server via https and not http as it does by default. This can be set using H2O_WAVE_ADDRESS="" env variable when starting the Wave app.

Deployment to separate machines

Although most people deploy their Wave server and Wave app to the same machine, it's not the only way. When deploying to separate machines, the main challenge is to make sure Wave server and Wave app can communicate properly.

For wave app machine, the following needs to be set:

  • H2O_WAVE_APP_ADDRESS - the address of the Wave app machine that Wave server connects to. Defaults to http://localhost:8000. In real world, this would be something like
  • H2O_WAVE_ADDRESS - the address of the Wave server machine. Defaults to http://localhost:10101. In real world, this would be something like
  • --host - Uvicorn exposes localhost by default, which would only listen for local network requests. tells it to listen on all addresses.

Do not specify addresses with https protocol if you haven't configured Wave server and Wave app to use TLS.


See a step-by-step blog post by Greg Fousas.


See a step-by-step blog post by Audrey Leteve.

Hugging Face Spaces

See a step-by-step blog post.

Behind Nginx (reverse proxy)

Since Wave relies on websockets, the following configuration is necessary.

# Enable websockets.
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;

server {
location / {
proxy_http_version 1.1;
; Change to your wave server address.
proxy_pass http://localhost:10101/;

proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Host $http_host;
proxy_set_header X-Forwarded-Proto http;
proxy_set_header X-NginX-Proxy true;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;

proxy_redirect off;

Read more at official Nginx docs or see an example repo.