Secure mode (HTTPS + mTLS)

Without certificates everything runs plain HTTP (easiest for local dev). Once certificates exist, weightslab start and the training backend both find them and switch on HTTPS between the browser and the UI server, and mTLS between the UI server and the backend. Set it up before running the Python experiment script:

  1. Generate TLS certificates once:

    weightslab se

    Certificates are placed in $WEIGHTSLAB_CERTS_DIR, else ~/.weightslab-certs. Follow the printed instructions to export WEIGHTSLAB_CERTS_DIR globally.

    On Windows, weightslab se runs the PowerShell script with the Windows openssl and adds the dev CA to your user’s trusted root certificates (Windows asks you to confirm). To generate the certificates through WSL (Ubuntu) instead, run:

    weightslab se --force-ubuntu

    The WSL path does not install the CA into the Windows trust store.

  2. Start the UI:

    weightslab start

    It reads $WEIGHTSLAB_CERTS_DIR (single source of truth). When the variable is unset, or its directory has no certs, ~/.weightslab-certs is used instead. With certs found it (--certs turns missing certs into a warning; --no-certs or GRPC_TLS_ENABLED=0 force plain HTTP):

    • Serves HTTPS using ui-server.crt / ui-server.key

    • Presents ui-client.crt / ui-client.key to the backend (mTLS)

    • Expects the backend CA at ca.crt

  3. Configure the backend to require mTLS::
    Should be automatic if certs have been created to default directory “~/.weightslab-certs”.

    export GRPC_TLS_ENABLED=1 export GRPC_TLS_REQUIRE_CLIENT_AUTH=1 export WEIGHTSLAB_CERTS_DIR=~/.weightslab-certs

Certificate files (all in $WEIGHTSLAB_CERTS_DIR)

File

Purpose

ca.crt

CA certificate (trusted by all parties)

ui-server.crt/.key

UI server TLS cert (browser to server)

ui-client.crt/.key

UI client mTLS cert (server to backend)

backend-server.crt/.key

Backend gRPC TLS cert (loaded by backend)

.grpc_auth_token

Optional token for gRPC metadata auth

Regenerate certificates at any time with weightslab se --force-certs.