Serve the one-line installer from rossoctl.dev instead of raw.githubusercontent.com #1354

Problem

The documented one-line install is:

curl -fsSL https://raw.githubusercontent.com/rossoctl/cortex/main/scripts/install.sh | sh

It works, but it reads as plumbing rather than a product. It leaks the org, the repo, the branch and the directory layout into the thing we most want people to copy-paste and trust. raw.githubusercontent.com is also the domain every sketchy curl | sh in the world uses, which is the opposite of the signal we want on a tool that installs a TLS-intercepting proxy and a CA.

We own rossoctl.dev. Proposal is to front the installer with something like:

curl -fsSL https://rossoctl.dev/cortex/install.sh | sh

Opening this to pick an approach before anyone writes code — there are real trade-offs, and one hard constraint (install stats) worth agreeing on first.

What already exists

Worth knowing before we design anything, because more is in place than it looks:

• rossoctl.dev apex resolves to 199.46.34.76, an IBM redirector (x-ibm-from-redirect: Yes), which 301s to https://www.rossoctl.dev/.
• www.rossoctl.dev is a CNAME to rossoctl.github.io — GitHub Pages, serving a Docusaurus v3.10.1 site built from the rossoctl/.github repo (static/CNAME, deployed by .github/workflows/deploy.yaml, Pages build_type: workflow). HTTPS cert approved through 2026-12-19. Netlify is PR deploy previews only.
• DNS is on NS1 (dns*.p05.nsone.net).

So we do not need to stand up hosting. We need to decide how a plain-text shell script gets served from a Docusaurus site, and from which repo.

Heads-up: that URL already returns HTTP 200

https://rossoctl.dev/cortex/install.sh returns 200 today — but it is serving the 29 KB Docusaurus homepage as text/html. The SPA answers 200 for every path (/definitely-not-a-real-path-xyz returns 200 too). Two consequences:

1. We cannot use a 404 to detect that the file is missing. Any verification must check the content, not the status code.
2. If we publish the new command before the file genuinely exists, users pipe HTML into sh. Harmless in effect, but a confusing first impression of a security tool. The docs change and the file landing must be the same change, or the file must land first.

Hard constraint: install stats must keep working

We estimate installs from GitHub Release asset download counts (scripts/collect-install-stats.sh, .github/workflows/install-stats.yaml), summed per platform with successful release-smoke-linux.yaml runs subtracted as CI.

Good news: a vanity front door does not touch this. The counted downloads come from the asset path, which is hardcoded independently of the installer URL:

base="https://github.com/${REPO}/releases/download/${version}"
# agentop_*.tar.gz, cortex_*.tar.gz, checksums.txt

Whoever serves install.sh, the script still pulls its tarballs and checksums.txt from GitHub Releases. The series stays continuous and comparable across the change — no backfill gap, no recalibration.

Two things to protect, though:

• The checksums.txt cross-check. checksums.txt is fetched exactly once per install regardless of platform, which is what validates the whole series (on v0.8.1 its 43 matched darwin_arm64 + linux_amd64 = 12 + 31). Any approach that caches, mirrors or proxies asset downloads would break this. None of the options below do — let's keep it that way.
• Don't expect a second counter. Pages gives us no server-side request logs, so the vanity URL cannot itself be counted. That is fine, but it means nobody should plan on "hits on install.sh" being available later. Asset downloads stay the single source of truth.

The complication: install.sh re-executes itself

scripts/install.sh is ~84 KB and does not run the copy you fetched. By default it resolves the newest release and re-downloads itself:

url="https://raw.githubusercontent.com/${REPO}/${want_ref}/scripts/install.sh"
# 404-fallback to ${want_ref}/install.sh, then ${want_ref}/authbridge/install.sh

The fallbacks exist for refs predating the #1134 flatten. The rationale is deliberate and documented in the header: a curl | sh should run a released installer, not whatever is on main.

This means a vanity URL is a front door, not a redirect of the whole flow. The bootstrap keeps fetching from raw.githubusercontent.com — which is arguably correct, since that is what makes --ref=vX.Y.Z pinning and the legacy fallbacks work. Worth deciding explicitly whether we are happy with that, or whether we want the re-exec rewritten too (bigger change, and it would need its own legacy story).

The URL is also hardcoded in three user-facing strings that must be updated together:

• scripts/install.sh:4 — header comment
• scripts/install.sh:197 — usage() heredoc
• scripts/install.sh:1429 — the upgrade/--ref hint printed at the end

Plus README.md Quick Start, and anywhere the docs site repeats it.

Options

A. Commit the script as a static asset in the site repo

Drop install.sh into rossoctl/.github at static/cortex/install.sh. Docusaurus copies static/ verbatim, so it ships as a real file.

• Simple, no new infrastructure, correct content-type, works on apex and www.
• Two copies of an 84 KB script that will drift, and the one users pipe to sh would be the stale one. This is the option that fails quietly and badly. If we pick it, it needs a CI drift check — at which point it is close to option C anyway.

B. Redirect /cortex/install.sh → raw.githubusercontent.com

Single source of truth, zero drift.

• GitHub Pages has no server-side redirect support. Docusaurus' client-redirects plugin emits an HTML page with a JS/meta refresh, which curl | sh cannot follow — it would pipe HTML to the shell. So plain Pages cannot do this.
• Two possible escapes, both needing someone to check feasibility:
  • The IBM apex redirector. It already 301s / → www. Can it do a path-scoped 301 to an arbitrary external URL? If yes, this is the cheapest correct answer. Needs someone with access to confirm — not determinable from outside.
  • A small Cloudflare Worker / equivalent on a subdomain or path, issuing a real 301/302. Correct and cheap, but adds a component and a second place DNS can break.
• Note curl -fsSL does follow redirects (-L), so a real HTTP redirect is fine. Only the HTML kind is not.

C. CI-synced copy on release

A workflow in cortex pushes scripts/install.sh to the site repo (or a gh-pages path) on every release.

• No drift, real text/plain, and it naturally publishes the released installer — which matches the script's own "install a release, not main" philosophy better than fronting main does.
• Costs cross-repo CI and a token with write access to the site repo. We already run a similar cross-repo pattern (install-stats.yaml pushes to gh-pages), so this is familiar ground rather than something new.

Decisions I'd like the team's view on

1. Which option — A, B, or C? My read: C is the most robust and best matches the released-installer guarantee; B is the most elegant if the IBM redirector can do path-based 301s; A is a trap without a drift check.
2. Apex or www? https://rossoctl.dev/... is the nicer URL but routes the install through the IBM redirector. https://www.rossoctl.dev/... hits Pages directly — one less hop, one less owner in the install path. Do we want IBM infrastructure in a curl | sh?
3. Path shape. /cortex/install.sh scales to other tools (/moca/install.sh) and is my preference. Alternatives: /install.sh (shortest, but claims the root for one tool) or /cortex/install (no extension — prettier, less obviously a script).
4. Keep raw.githubusercontent.com working? I'd say yes, indefinitely — it is in the wild, in people's notes, and in the re-exec fallbacks. Vanity URL as the documented front door, raw URL as a permanent unadvertised alias.
5. Does the re-exec stay as-is? I lean yes for now — it is what makes --ref pinning work — but it means the vanity URL is cosmetic past the first hop. Flagging it so nobody is surprised later.
6. Verification. Given the SPA-200 problem, any CI check must assert on content (e.g. first line is #!/bin/sh) rather than status. Worth a smoke check that the published URL serves a real script.

Scope note

This is deliberately not a plan to rewrite the installer. The change is: pick a hosting approach, land the file, update three strings in install.sh plus the README and docs, keep the old URL alive, and add a content-based check. Install stats need no change.