vix proxy manages reverse proxy configuration for a Vix application.

Use it when you want to expose a Vix backend through Nginx, configure a domain, enable WebSocket proxying, validate proxy rules, reload Nginx, or issue a Let's Encrypt certificate.

vix proxy nginx init

vix proxy is the production reverse proxy command for Vix.

It helps connect a local Vix application to a public domain.

It can:

• generate an Nginx site config
• install the config under /etc/nginx/sites-available
• enable the site under /etc/nginx/sites-enabled
• validate Nginx configuration
• reload Nginx safely
• configure HTTP reverse proxying
• configure WebSocket reverse proxying
• configure HTTPS redirects
• validate TLS certificate paths
• check TLS certificate quality when crypto support is available
• issue or renew Let's Encrypt certificates with Certbot
• detect missing proxy headers
• detect wrong upstream ports
• detect missing WebSocket upgrade headers
• detect missing proxy timeouts

This command is part of the Vix production workflow.

The goal is to avoid manually writing and debugging Nginx configs for every Vix backend.

vix proxy is currently supported on:

Linux

The Nginx provider uses:

nginx
systemctl
sudo
certbot
/etc/nginx/sites-available
/etc/nginx/sites-enabled
/etc/letsencrypt/live

On unsupported platforms, Vix reports that vix proxy is currently supported on Linux only.

vix proxy <provider> <command>

Currently supported provider:

nginx

vix proxy nginx <command>

# Generate and install Nginx config
vix proxy nginx init

# Validate installed Nginx proxy config
vix proxy nginx check

# Validate and reload Nginx
vix proxy nginx reload

# Issue or renew a Let's Encrypt certificate
vix proxy nginx certbot

A common production setup looks like this:

vix build --preset release
vix service install
vix service start
vix proxy nginx init
vix proxy nginx check
vix doctor production

If you want HTTPS with Let's Encrypt:

vix proxy nginx certbot
vix proxy nginx check
vix doctor production

After changing proxy configuration:

vix proxy nginx init
vix proxy nginx reload
vix doctor production

vix proxy nginx reads configuration from:

vix.json

under:

production.proxy

Example:

{
  "name": "PulseGrid",
  "production": {
    "proxy": {
      "domain": "pulsegrid.example.com",
      "http": {
        "port": 8080
      },
      "websocket": {
        "enabled": true,
        "path": "/ws",
        "port": 9090
      },
      "tls": {
        "enabled": true
      }
    }
  }
}

Vix detects the app name from:

vix.json name
*.vix file name
current directory name

The app name is used for Nginx site files.

For an app named:

PulseGrid

Vix writes:

/etc/nginx/sites-available/PulseGrid
/etc/nginx/sites-enabled/PulseGrid

The domain is required.

Example:

{
  "production": {
    "proxy": {
      "domain": "pulsegrid.example.com"
    }
  }
}

If the domain is missing, Vix prints:

Missing proxy domain.
Fix: add production.proxy.domain to vix.json

The HTTP proxy forwards public HTTP traffic to the local Vix app.

Example config:

{
  "production": {
    "proxy": {
      "domain": "pulsegrid.example.com",
      "http": {
        "port": 8080
      }
    }
  }
}

This creates an upstream like:

proxy_pass http://127.0.0.1:8080;

The generated config includes important proxy headers:

proxy_set_header Connection "";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

It also includes HTTP proxy timeouts:

proxy_connect_timeout 10s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;

Enable WebSocket proxying when your app exposes a WebSocket endpoint.

Example:

{
  "production": {
    "proxy": {
      "domain": "pulsegrid.example.com",
      "http": {
        "port": 8080
      },
      "websocket": {
        "enabled": true,
        "path": "/ws",
        "port": 9090
      }
    }
  }
}

This generates a WebSocket location like:

location = /ws {
    proxy_pass http://127.0.0.1:9090/;
    proxy_http_version 1.1;

    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";

    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
    proxy_buffering off;
}

If the WebSocket path does not start with /, Vix normalizes it.

Example:

{
  "production": {
    "proxy": {
      "websocket": {
        "enabled": true,
        "path": "ws",
        "port": 9090
      }
    }
  }
}

Vix treats it as:

/ws

If no path is provided, the default shape is:

/ws

Enable TLS when you want HTTPS.

Example:

{
  "production": {
    "proxy": {
      "domain": "pulsegrid.example.com",
      "http": {
        "port": 8080
      },
      "tls": {
        "enabled": true
      }
    }
  }
}

When TLS is enabled and a domain is configured, Vix uses Let's Encrypt style default paths:

/etc/letsencrypt/live/<domain>/fullchain.pem
/etc/letsencrypt/live/<domain>/privkey.pem

For example:

/etc/letsencrypt/live/pulsegrid.example.com/fullchain.pem
/etc/letsencrypt/live/pulsegrid.example.com/privkey.pem

You can also set explicit certificate paths:

{
  "production": {
    "proxy": {
      "domain": "pulsegrid.example.com",
      "tls": {
        "enabled": true,
        "certificate": "/etc/letsencrypt/live/pulsegrid.example.com/fullchain.pem",
        "certificate_key": "/etc/letsencrypt/live/pulsegrid.example.com/privkey.pem"
      }
    }
  }
}

When TLS is enabled, Vix generates two server blocks:

1. HTTP server on port 80
2. HTTPS server on port 443

The HTTP block redirects to HTTPS:

return 301 https://$host$request_uri;

The HTTPS block serves the app through the configured upstream.

If TLS is disabled, Vix generates a plain HTTP config.

Example:

{
  "production": {
    "proxy": {
      "domain": "pulsegrid.example.com",
      "http": {
        "port": 8080
      },
      "tls": {
        "enabled": false
      }
    }
  }
}

This generates only a port 80 server block.

Run:

vix proxy nginx init

This command:

1. loads production.proxy from vix.json
2. prints a proxy summary
3. renders an Nginx config
4. writes the config to a temporary file
5. copies it to /etc/nginx/sites-available/<app>
6. enables it with a symlink under /etc/nginx/sites-enabled/<app>
7. runs sudo nginx -t
8. reloads Nginx
9. prints success when the proxy is installed

You may be asked for sudo permission.

Example output shape:

Proxy Init
App: PulseGrid
Domain: pulsegrid.example.com
HTTP: 127.0.0.1:8080
WebSocket: 127.0.0.1:9090 /ws
TLS: enabled
Site file: /etc/nginx/sites-available/PulseGrid
Enabled path: /etc/nginx/sites-enabled/PulseGrid
Certificate: /etc/letsencrypt/live/pulsegrid.example.com/fullchain.pem
Certificate key: /etc/letsencrypt/live/pulsegrid.example.com/privkey.pem

Run:

vix proxy nginx check

This validates the installed proxy config.

It checks:

• domain exists
• site file exists
• site is enabled
• server_name matches
• HTTP upstream port matches
• forwarded headers exist
• HTTP proxy timeouts exist
• WebSocket location exists when enabled
• WebSocket upstream port matches when enabled
• WebSocket upgrade headers exist when enabled
• WebSocket timeouts exist when enabled
• TLS certificate paths match when TLS is enabled
• HTTPS redirect exists when TLS is enabled
• Nginx is installed
• sudo nginx -t passes
• TLS certificate looks valid when crypto support is available

Example output shape:

Proxy Check
App: PulseGrid
Domain: pulsegrid.example.com
HTTP upstream: 127.0.0.1:8080
WS upstream: 127.0.0.1:9090 /ws
TLS: enabled
Site file: /etc/nginx/sites-available/PulseGrid
Enabled: yes

If everything is correct:

nginx config is valid
proxy config looks good

Run:

vix proxy nginx reload

This command runs the proxy check first.

If the check fails, reload is aborted.

Proxy check failed. Nginx reload aborted.
Fix: run `vix proxy nginx check`

If the check passes, Vix reloads Nginx:

sudo systemctl reload nginx

If Nginx is not active, Vix suggests starting it:

sudo systemctl start nginx

Run:

vix proxy nginx certbot

This command helps bootstrap HTTPS.

It performs this flow:

1. checks that production.proxy.domain exists
2. checks that nginx is available
3. checks that certbot is available
4. installs a temporary HTTP config
5. validates Nginx config
6. reloads or starts Nginx
7. runs sudo certbot --nginx -d <domain>
8. checks the generated certificate files
9. installs the final Vix TLS proxy config
10. validates Nginx config again
11. reloads or starts Nginx again

This is useful because Certbot often needs a working HTTP config before issuing the first certificate.

vix proxy nginx certbot requires:

nginx
certbot

If Certbot is missing, Vix suggests:

sudo apt install certbot python3-certbot-nginx

Vix runs a command shaped like:

sudo certbot --nginx -d pulsegrid.example.com

After Certbot succeeds, Vix expects:

/etc/letsencrypt/live/pulsegrid.example.com/fullchain.pem
/etc/letsencrypt/live/pulsegrid.example.com/privkey.pem

Then it installs the final TLS config.

When Vix is built with crypto support, vix proxy nginx check can inspect the TLS certificate.

It can detect:

• invalid PEM X.509 certificate
• expired certificate
• certificate domain mismatch

If crypto support is not available in the current Vix CLI build, Vix reports:

TLS certificate checks are not available in this build.
Fix: rebuild the Vix CLI with the crypto module enabled

{
  "name": "PulseGrid",
  "production": {
    "proxy": {
      "domain": "pulsegrid.example.com",
      "http": {
        "port": 8080
      },
      "tls": {
        "enabled": false
      }
    }
  }
}

Then run:

vix proxy nginx init
vix proxy nginx check

{
  "name": "PulseGrid",
  "production": {
    "proxy": {
      "domain": "pulsegrid.example.com",
      "http": {
        "port": 8080
      },
      "tls": {
        "enabled": true
      }
    }
  }
}

Then run:

vix proxy nginx certbot
vix proxy nginx check

{
  "name": "PulseGrid",
  "production": {
    "proxy": {
      "domain": "pulsegrid.example.com",
      "http": {
        "port": 8080
      },
      "websocket": {
        "enabled": true,
        "path": "/ws",
        "port": 9090
      },
      "tls": {
        "enabled": true
      }
    }
  }
}

Then run:

vix proxy nginx certbot
vix proxy nginx check
vix doctor production

With HTTPS and WebSocket enabled, Vix generates a config shaped like this:

server {
    listen 80;
    listen [::]:80;
    server_name pulsegrid.example.com;

    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name pulsegrid.example.com;

    ssl_certificate /etc/letsencrypt/live/pulsegrid.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/pulsegrid.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;

        proxy_set_header Connection "";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_connect_timeout 10s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }

    location = /ws {
        proxy_pass http://127.0.0.1:9090/;
        proxy_http_version 1.1;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
        proxy_buffering off;
    }
}

vix service manages the app process.

vix proxy nginx manages the public reverse proxy.

A complete backend production setup usually needs both:

vix build --preset release
vix service install
vix service start
vix proxy nginx certbot
vix doctor production

vix doctor production inspects the production state.

After configuring the proxy, run:

vix doctor production

It can detect:

• Nginx proxy configured
• proxy target
• public URL
• TLS status
• local health
• public health
• readiness score

vix proxy nginx validates proxy configuration.

vix health validates runtime availability.

After proxy setup, use:

vix health local
vix health public

Then:

vix doctor production

For a public HTTP app:

vix build --preset release
vix service install
vix service start
vix proxy nginx init
vix proxy nginx check
vix doctor production

For a public HTTPS app:

vix build --preset release
vix service install
vix service start
vix proxy nginx certbot
vix proxy nginx check
vix doctor production

For a public HTTPS app with WebSocket:

vix build --preset release
vix service install
vix service start
vix proxy nginx certbot
vix proxy nginx check
vix health public
vix doctor production

vix proxy nginx init
vix proxy nginx check

vix proxy nginx certbot
vix proxy nginx check

vix proxy nginx init
vix proxy nginx check

vix proxy nginx check
vix proxy nginx reload

vix doctor production

Wrong:

{
  "production": {
    "proxy": {
      "http": {
        "port": 8080
      }
    }
  }
}

Correct:

{
  "production": {
    "proxy": {
      "domain": "pulsegrid.example.com",
      "http": {
        "port": 8080
      }
    }
  }
}

If your app listens on port 8080, configure:

{
  "production": {
    "proxy": {
      "http": {
        "port": 8080
      }
    }
  }
}

Then run:

vix proxy nginx init
vix proxy nginx check

Do not edit the generated Nginx config manually unless needed.

If vix proxy nginx check says WebSocket upgrade headers are missing, regenerate:

vix proxy nginx init

If TLS is enabled and certificate files do not exist yet, use:

vix proxy nginx certbot

This bootstraps HTTP first, runs Certbot, then installs the final TLS config.

reload already runs check.

If check fails, reload is aborted.

Use:

vix proxy nginx check

to see the exact issue.

vix proxy nginx manages Nginx.

It does not start your Vix app.

Start the app with:

vix service start

or run it manually with:

vix run

vix proxy nginx does not build the app.

Build first:

vix build --preset release

Then configure service and proxy.

Install Nginx:

sudo apt install nginx

Then run:

vix proxy nginx init

Install Certbot:

sudo apt install certbot python3-certbot-nginx

Then run:

vix proxy nginx certbot

Run:

sudo nginx -t

Then regenerate:

vix proxy nginx init

Check whether Nginx is active:

systemctl is-active nginx

Start it:

sudo systemctl start nginx

Or reload it:

sudo systemctl reload nginx

Then run:

vix proxy nginx check

If check reports:

Nginx site file not found

run:

vix proxy nginx init

If check reports that the site is not enabled, run:

vix proxy nginx init

Or manually create the symlink shown by Vix.

Check:

{
  "production": {
    "proxy": {
      "domain": "pulsegrid.example.com"
    }
  }
}

Then issue or renew:

vix proxy nginx certbot

Renew:

vix proxy nginx certbot

Then check:

vix proxy nginx check

Check the full stack:

vix service status
vix service health
vix proxy nginx check
vix health public
vix doctor production

Common causes:

• app service is not running
• wrong HTTP port
• wrong WebSocket port
• Nginx config not enabled
• TLS certificate missing
• DNS does not point to the server
• firewall blocks ports 80 or 443

Keep proxy configuration in vix.json.

Use vix proxy nginx init instead of editing Nginx config manually.

Use vix proxy nginx check before debugging public health.

Use vix proxy nginx reload instead of reloading Nginx manually.

Use vix proxy nginx certbot for first-time HTTPS setup.

Use WebSocket config only when your app actually exposes a WebSocket endpoint.

Run vix doctor production after proxy changes.

Run vix health public after TLS changes.

Do not ignore warnings from vix proxy nginx check.

Check production readiness.

Open the production doctor guide