Security & Access

Access Levels

Suwu automatically detects where you're connecting from and applies the right level of access:

• Localhost — open https://127.0.0.1:8181 after onboarding.
• LAN — accessible from your local network with the required onboarding password.
• Internet — behind a reverse proxy. HTTPS and strong auth required.

Password Authentication

Onboarding requires a password. You can choose one or have Suwu generate a secure password for you:

suwu onboard
# The password is highlighted in the final summary.
# AUTH_PASS stores only its SHA-256 hash.

The web UI prompts for the onboarding password on first access. Sessions are authenticated via a secure cookie.

Per-Run Tokens

For temporary access, Suwu generates a per-run token displayed in the terminal when the server starts. Share this token with someone who needs one-time access — it's valid only for the current server run.

$ suwu serve
  ┌──────────────────────────────────────┐
  │  Suwu is running                     │
  │  https://127.0.0.1:8181              │
  │  Token: abc123xyz                    │
  └──────────────────────────────────────┘

HTTPS with One Command

Suwu can generate a self-signed certificate and enable HTTPS in one step:

# Generate certs and configure HTTPS
suwu gencerts

# The cert paths are written to ~/.config/suwu/.env
# Restart the server to pick them up
suwu serve

For production use, provide your own certificates:

TLS_CERT_FILE=/path/to/cert.pem \
TLS_KEY_FILE=/path/to/key.pem \
suwu serve

Reverse Proxy Setup

For internet access, put Suwu behind a reverse proxy (nginx, Caddy, etc.). The key headers to forward:

# nginx example
location / {
    proxy_pass http://127.0.0.1:8180;
    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;
}

Environment Variables

Variable	Description
SERVER_MODE	https, http, or https+http (default: https)
HTTPS_PORT / HTTP_PORT	Listener ports (defaults: 8181 / 8180)
HOST	Bind address (127.0.0.1 default, 0.0.0.0 for all interfaces)
EXTRA_HOSTS	Additional allowed hosts, e.g. example.com,*.lan.example
AUTH_PASS	SHA-256 hash of the required web password; set by suwu onboard
TLS_CERT_FILE	Path to TLS certificate
TLS_KEY_FILE	Path to TLS private key