docs(self-hosting): public guides, agent runbooks and downloadable helper files
What
Makes the self-hosting docs public. The login gate, the per-request Cloud fetch and the entitlement check are gone: the guides are now plain Markdown in the repo (web/content/self-hosting/*.md), prerendered like the rest of the docs, in the sitemap and in llms.txt.
The content is rewritten as short, numbered guides with a Done when check on every step, merging the old runbooks with the field-tested EKS and GKE install material from this week. Where they disagreed, the newer material wins (releases agent-relay-2026.11.0 for EKS, agent-relay-2026.11.1 for GKE).
Pages (/docs/self-hosting/...)
| Group | Pages |
|---|---|
| Start | Overview (what you get, how it fits together, choose your path, releases, sizing and scaling, availability, guided install with the setup agent) |
| Install on AWS | Install on EKS (16 steps) · Use an existing or shared RDS · Bring your own AWS resources · IAM and Pod Identity |
| Install on Google Cloud | Install on GKE (15 steps, marked tested on GKE, with known limits) · Bring your own Google Cloud resources (incl. Workload Identity grants) |
| Configure | Secrets (kubectl, helm-secrets/SOPS, vals + SSM, vals + Google Secret Manager) · Single sign-on with Okta · After the install (Output coverage, titles and summaries, agent-name filter) · Desktop app rollout |
| Operate | Upgrades · Backup and restore · Telemetry · Durable actors · Troubleshooting · Teardown · Support |
| Reference | Downloads (every helper file with its SHA-256) |
Agent track
/docs/self-hosting/agents(rules for coding agents: never print secrets, ask before every change, who runs credential-printing commands, DNS is the human's) and/docs/self-hosting/agents/<guide>for every guide.- One source: each guide file carries
<!-- agent ... -->blocks. Humans never see them (HTML comments don't render); the agent runbook turns them into> **Agent:**callouts with explicit ASK THE HUMAN / STOP points, and rewrites links to the agent runbooks. - Raw Markdown for both tracks, same convention as
/docs/<slug>.md:/docs/self-hosting.md,/docs/self-hosting/<guide>.md,/docs/self-hosting/agents.md,/docs/self-hosting/agents/<guide>.md(served fromapp/docs/self-hosting/markdown/[...path], prerendered, CORS like the other.mdmirrors). - llms.txt gets a Self-hosting section (human guides plus the agent runbooks); llms-full.txt includes the human guides. The agent runbooks stay out of the sitemap, like the other agent pages.
Downloadable helper files
web/public/self-hosting/files/{eks,gke}/ holds the helper scripts and values.yaml templates, each folder with a SHA256SUMS. Step 1 of each install guide is now curl + shasum -a 256 -c SHA256SUMS instead of cloning a gist. Only comments pointing at the old gist file names were changed; script logic is as tested. web/scripts/selfhost-files.mjs write|check regenerates the sums and the Downloads table; a test fails if either is stale.
Removed
- The gate in
app/docs/self-hosting/[[...slug]]/page.tsx: session cookie,/loginredirect, CloudGET /cloud/api/v1/me/selfhost-docsfetch, entitlement and "request access" pages,force-dynamic,robots: noindex, theph-sensitive/ph-no-capturereplay block. lib/selfhost-docs.tsCloud client (fetchSelfhostDocs, cookie/session validation,SELFHOST_DOCS_CLOUD_ORIGIN,SELFHOST_DOCS_HEADERS), and theselfhost:<name>reference linking in the renderer.next.config.mjsprivate, no-store/noindex/no-referrer/ CSP header block for/docs/self-hosting.scripts/selfhost-docs-leak-check.mjs,security/selfhost-runbook-fingerprints.jsonand its test, and the leak-check step indeploy.yml,preview.ymlandverify.yml.verify-worker.mjs: the "signed-out reader is redirected, uncached" smoke check, replaced by checks that the pages, Markdown mirrors andSHA256SUMSserve publicly and withoutnoindex.- Router:
isSelfhostDocsPathexcluded the gated pages, Cloud's sign-in return hop and Cloud's runbook API from the replay recorder. Its only consumer is the recorder; the pages are now ordinary public docs, so the exclusion is narrowed to Cloud's runbook API, which still serves private runbooks until it is retired (isSelfhostRunbookApiPath). Nothing else imported it.
Checks
npm run typecheck: pass (web and router).npm run lint: 0 errors; the same 4 warnings asmain.- web
vitest run: 53 files, 602 tests pass. New tests cover: every guide file listed once with a title and description; links between guides resolve; every numbered install step has a Done-when; human vs agent rendering; routes,.mdrewrites ordered before the generic docs rule, no private/no-store/noindex headers; sitemap and llms.txt entries;SHA256SUMSand the Downloads table up to date; everybash <script>an install guide runs is downloadable; and a hashed guard against a customer domain, install ID, our cloud account IDs and internal test hosts appearing in any public guide or helper file. - router
vitest run: 11 files, 120 tests pass (run with an isolated config: a vitest config in the parent directory of my local checkout otherwise hijacks discovery; not a repo issue). npm run build: pass. Every guide, agent runbook and.mdmirror prerenders. Withnext starton the build: all pages and.mdURLs answer 200 withindex, follow, unknown guides 404, the sitemap lists 19 self-hosting URLs, and downloading/self-hosting/files/eks/*thenshasum -a 256 -c SHA256SUMSpasses. The Cloudflare Worker smoke (verify-worker.mjs) only runs in CI.
Privacy check: I grepped the whole diff for the customer's name and domain, the install ID, our AWS/GCP account and project IDs, internal test hostnames, internal agent names, Slack/relay references, people's names and secret patterns: no hits. The only near-miss is the literal PIPELINE_KEY_PREFIX: 96bulls in the two values.yaml templates and the bulls96_* database role names inside rds-setup.sh: these are functional values the public chart requires (charts/session-read-api fails the render without that literal), already public in AgentWorkforce/infra.
Not verified / follow-ups
- Not run end to end from these pages. The commands are the ones tested this week (EKS on 2026.11.0 including a shared RDS dry run; GKE on 2026.11.1), but nobody has yet run an install by following the published pages and downloading from
agentrelay.com/self-hosting/files. - GKE transcript reads need the Sessions image from the release after 2026.11.1 (relayhistory-pipeline #571). The GKE page says so under Known limits; update it when that release is cut. The GKE guide's source PR (AgentWorkforce/infra#277, with #276) is still open;
cloud-sql-setup.shhere is the fixed copy. - Not rehearsed: GKE teardown, the 2026.11 backup/restore drill (the old GCP scripted drill was built for an earlier profile; the page says so), Okta on GKE, durable actors on the 2026.11 profiles.
- Follow-up: point relay-agent at the public docs.
relay-agentknowledge/private/selfhost/*is unchanged (the support agent still reads it, and the guided-install prompts on the overview still work). A follow-up can point it at/docs/self-hosting/agents/*.mdand retire Cloud'sGET /cloud/api/v1/me/selfhost-docsendpoint; then the router's remainingisSelfhostRunbookApiPathexclusion can go too. - The two architecture SVGs in
public/img/self-hosting/are drawn for the older chart (RelayHistory, RelayAuth); the overview now uses a table instead. They are unused and can be redrawn or deleted.
Not merged or deployed.
🤖 Generated with Claude Code
![Autofix with [code]smith](https://pr-comments-assets.blacksmith.sh/codesmith/autofix-with-codesmith-dark-3x.png)
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.
Summary by cubic
Makes the self-hosting docs publicly accessible without a login. The session gate, per-request Cloud fetch, and entitlement check are removed; the guides are now plain Markdown in the repo, prerendered like the rest of the docs, and included in the sitemap and llms.txt.
Content
- Rewrites the runbooks as numbered guides with a "Done when" check per step, merging the old runbooks with the field-tested EKS (
agent-relay-2026.11.0) and GKE (agent-relay-2026.11.1) install material, with the newer material winning on disagreement. - Adds an agent track at
/docs/self-hosting/agents/<guide>generated from the same files:<!-- agent -->blocks become "Agent:" callouts with explicit ASK THE HUMAN / STOP points, plus raw.mdmirrors for both tracks. - Marks single sign-on (Okta) as an Enterprise feature, documents that the install tooling carries the FSL-1.1-ALv2 license from
agent-relay-2026.11.2, and adds a licensing section to the overview. - Serves the helper scripts and
values.yamltemplates from/self-hosting/files/{eks,gke}withSHA256SUMS; install guides now download and verify them instead of cloning a gist.
Removed
- The Cloud
selfhost-docsclient, the leak-check script and its fingerprint file, and the corresponding CI steps. - The router's docs replay exclusion, narrowed to Cloud's runbook API, which still serves private runbooks until it is retired.
- The indexable check on workers.dev previews, which Cloudflare marks noindex.