Skip to content

Serve the studio over HTTPS (exposed bind)

When you expose the studio beyond localhost — the mobile cockpit, keryx studio --host 0.0.0.0 — it serves HTTPS and marks the session cookie Secure, so the access token can't leak to a LAN eavesdropper. Loopback binds stay plain http and open (single-user dev). This is spec 0027.

What happens on an exposed bind

keryx studio --host 0.0.0.0   # or a specific LAN IP
  1. keryx obtains a TLS certificate from the configured cert source (below).
  2. It serves https://… and prints the token URL over https.
  3. The session cookie set from that URL is Secure + HttpOnly + SameSite=Strict.

A loopback bind (keryx studio, the default) is unchanged: plain http, no token, no cookie.

Skip the token on a trusted network (--no-auth)

The exposure token rotates every start, so a bookmarked URL expires on each restart — fine for a one-off, annoying for iterative work or a stable remote bookmark. On a network you trust, opt out:

keryx studio --host 192.168.0.5 --no-auth

It still serves HTTPS, but skips the token gate — the URL is just https://192.168.0.5:PORT, stable across restarts. keryx logs a loud warning: anyone who can reach the address has full access, so use it only on a trusted LAN / VPN, never on an untrusted network.

Cert sources (tls.source)

tls.source Behaviour
localca (default) A browser-trusted cert from a per-machine local CA. First run installs the CA into your trust store (one elevation prompt); no warning thereafter. Falls back to self-signed if it can't provision.
selfsigned A self-signed cert — HTTPS with a one-time browser warning. Zero setup, installs nothing.

Set it in config:

tls:
  source: localca   # or: selfsigned

First run with localca

The first exposed bind mints a per-machine root CA, installs it into your system (and, if certutil is present, Firefox/Chromium) trust store, and issues a leaf for localhost, the loopback addresses, and your bind host/IP. Installing into the system store needs elevation:

  • Linux / macOS: a sudo password prompt in the terminal you launched from. keryx pre-warms it so you're asked once.
  • No terminal available, or you decline? keryx falls back to a self-signed cert — still HTTPS (so the Secure cookie holds), just with a browser warning.

Install certutil (for Firefox trust) with apt install libnss3-tools / dnf install nss-tools / brew install nss.

Trusting the cert on other devices

The root is installed only on the serving machine. To silence the warning on a phone or another laptop, import the root — it's under keryx's config dir at localca/rootCA.pem.

Removing the local CA

The local CA is reversible. Re-mint or remove it by clearing keryx's localca data dir (under the config dir) and, if you installed it, removing the root from your trust store (localca/rootCA.pem is the cert to remove).

The OAuth callback loopback

keryx auth instagram runs an https callback (Meta rejects http://localhost), so it uses the same cert source as the studio: once the local CA is installed, the callback is browser-trusted with no warning; otherwise it falls back to a self-signed cert (one warning). Because both surfaces share the same per-machine root (under keryx's localca data dir), installing it via keryx studio or keryx auth covers both. The other platforms (YouTube, TikTok, LinkedIn) use a plain-http loopback and need no cert.