From 9ed6272dc71b0eab671bc522267e5669163c1f7a Mon Sep 17 00:00:00 2001 From: Erich Blume Date: Fri, 5 Jun 2026 06:43:54 -0700 Subject: [PATCH] heph docs: spoke sync uses direct http://...:8787, not Caddy HTTPS MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit hephd's sync client is plain-HTTP-only — a Caddy https hub-url fails with a confusing 'error sending request' (HTTP connector rejects the https scheme). Spokes sync over the direct tailnet URL; heph.ops.eblu.me is for the PWA only. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/reference/services/hephaestus.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/docs/reference/services/hephaestus.md b/docs/reference/services/hephaestus.md index 838e440..1754ea0 100644 --- a/docs/reference/services/hephaestus.md +++ b/docs/reference/services/hephaestus.md @@ -18,7 +18,8 @@ against one canonical **hub**. Indri runs that hub. | Property | Value | |----------|-------| -| **URL** | https://heph.ops.eblu.me (PWA + sync endpoint) | +| **PWA URL** | https://heph.ops.eblu.me (browser PWA, Caddy TLS) | +| **Spoke sync URL** | http://indri.tail8d86e.ts.net:8787 (direct, tailnet) | | **Local Port** | 8787 (`hephd --mode server`, bound `0.0.0.0`) | | **Binary** | `~/.cargo/bin/hephd` (self-updating) | | **Data** | `~/.local/share/heph/heph.db` | @@ -99,13 +100,22 @@ A device joins by running its local daemon with the hub URL + OIDC client and logging in once: ```bash -hephd --mode local --hub-url https://heph.ops.eblu.me \ +hephd --mode local --hub-url http://indri.tail8d86e.ts.net:8787 \ --oidc-issuer https://authentik.ops.eblu.me/application/o/heph/ \ --oidc-client-id heph -heph auth login --hub-url https://heph.ops.eblu.me \ +heph auth login --hub-url http://indri.tail8d86e.ts.net:8787 \ --issuer https://authentik.ops.eblu.me/application/o/heph/ --client-id heph ``` +> **Use the direct `http://…:8787` tailnet URL for sync, not the Caddy HTTPS +> URL.** hephd's sync client is plain-HTTP-only; pointing `--hub-url` at +> `https://heph.ops.eblu.me` fails with a confusing `error sending request` +> (the HTTP connector rejects the `https` scheme before connecting). Tailscale +> encrypts the transport, and the OIDC bearer token still gates every request. +> `heph.ops.eblu.me` (Caddy TLS) exists only for the browser PWA, which needs a +> secure context. The cached token is keyed by the exact `--hub-url`, so use the +> same value for `hephd` and `heph auth login`. + > **Caveat:** `heph daemon` cannot yet bake hub/spoke flags into the generated > launchd plist (upstream gap). On a spoke whose plist is managed by `heph > daemon`, the hub/OIDC flags must be hand-added — and a later `heph daemon