doc: configuring rivet endpoints

[NathanFlurry]

No description provided.

[NathanFlurry]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• doc: update railway integration guide for serverless #3897
• doc: configuring rivet endpoints #3895 👈 (View in Graphite)
• chore(rivetkit): validate incoming serverless request endpoint/namespace #3894
• chore(rivetkit): update welcome message #3893
• feat(rivetkit): allow defining public namespace & token for client redirects via metadata endpoint #3891
• chore(engine): provide detailed error for invalid serverless sse event #3881 : 1 other dependent PR (#3890 )
• main

---

How to use the Graphite Merge Queue

Add the label merge-queue to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

PR Review: Documentation Refactor for Rivet Endpoints

Summary

This PR reorganizes documentation for Rivet endpoint configuration by:

• Moving self-hosting connection docs to a new general "Endpoints" page
• Consolidating runner configuration into "Runtime Modes"
• Renaming "Server Setup" to "HTTP Server" for clarity
• Updating all internal links

✅ Strengths

Content Organization

• Excellent restructuring that separates concerns more clearly
• The new /docs/connect/endpoints page provides better progressive disclosure (local dev → production → advanced)
• Moving runner configuration to runtime-modes.mdx makes logical sense since runners are a runtime mode

Documentation Quality

• Clear distinction between private and public endpoints with security guidance
• Good use of tabs for environment variables vs. config options
• Helpful security warning about public tokens (pk_ vs sk_)
• Added visual diagram for endpoint architecture

Consistency

• All internal links properly updated across 7 files
• Sitemap correctly reflects the new structure

⚠️ Issues Found

1. Incorrect Link Reference (line 50 in endpoints.mdx)

The public endpoint is only required if using the [serverless runtime mode](/docs/general/runtime-modes#runners)

This links to #runners but should link to #serverless. The text says "serverless runtime mode" but anchors to the runners section.

Fix:

The public endpoint is only required if using the [serverless runtime mode](/docs/general/runtime-modes#serverless)

2. Repetitive Phrasing (line 117 in endpoints.mdx)

This is because Rivet handles routing, load balancing, and actor lifecycle management of actors.

The phrase "of actors" is redundant after "actor lifecycle management."

Fix:

This is because Rivet handles routing, load balancing, and actor lifecycle management.

3. Missing Environment Variables in Reference Table

The reference table at the bottom of endpoints.mdx doesn't include RIVET_NAMESPACE as a standalone variable, but it's documented in the "Advanced" section (line 91). The reference table should be comprehensive.

Fix: Add this row to the reference table:

| `RIVET_PUBLIC_NAMESPACE` | `serverless.publicNamespace` | Client-facing namespace |

Or clarify in the advanced section that namespace is only available embedded in URLs, not as a standalone env var for public endpoints.

4. Inconsistent Terminology

In runtime-modes.mdx line 45, there's a link:

See [Server Setup](/docs/general/http-server/) for more configuration options.

But the link text still says "Server Setup" while the page has been renamed to "HTTP Server". Should use consistent naming.

Fix:

See [HTTP Server](/docs/general/http-server/) for more configuration options.

💡 Suggestions (Optional)

1. Code Examples: In the runner configuration section (runtime-modes.mdx:106-113), consider showing where/how actors specify which runner pool they want. Currently only shows setup config but not actor-level usage.

2. Migration Guide: Users with existing bookmarks to /docs/self-hosting/connect-backend will get 404s. Consider adding a redirect or note in the self-hosting index about where this content moved.

3. Endpoint Validation: The GET /api/rivet/metadata endpoint mentioned in endpoints.mdx:59 says it "Validates configuration" but in line 105-113 it's described as returning public endpoint configuration. These seem like different purposes - clarify if it does both or update the description.

📊 Overall Assessment

Code Quality: ✅ N/A (documentation only)
Correctness: ⚠️ One incorrect anchor link
Clarity: ✅ Significant improvement
Completeness: ⚠️ Minor gaps in reference table
Security: ✅ Good security guidance included

Verdict

Approve with minor changes recommended. The refactor significantly improves documentation structure and clarity. The issues found are minor and easy to fix. The incorrect anchor link (issue #1) should be fixed before merge to avoid user confusion.

[pkg-pr-new]

More templates

• actor-actions
• example-ai-agent
• example-ai-and-user-generated-actors-freestyle
• chat-room
• example-cloudflare-workers
• example-cloudflare-workers-hono
• example-cloudflare-workers-inline-client
• cross-actor-actions
• example-cursors
• example-cursors-raw-websocket
• custom-serverless
• example-sqlite
• example-elysia
• example-experimental-durable-streams-ai-agent
• hello-world
• example-hono
• hono-react
• example-kitchen-sink
• multi-region
• native-websockets
• next-js
• example-raw-fetch-handler
• example-raw-websocket-handler
• example-raw-websocket-handler-proxy
• example-react
• scheduling
• state
• example-stream
• example-trpc

@rivetkit/cloudflare-workers

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/cloudflare-workers@3895

@rivetkit/db

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/db@3895

@rivetkit/framework-base

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/framework-base@3895

@rivetkit/next-js

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/next-js@3895

@rivetkit/react

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/react@3895

rivetkit

pnpm add https://pkg.pr.new/rivet-dev/rivet/rivetkit@3895

@rivetkit/sql-loader

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/sql-loader@3895

@rivetkit/virtual-websocket

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/virtual-websocket@3895

@rivetkit/engine-runner

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner@3895

@rivetkit/engine-runner-protocol

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner-protocol@3895

commit: 52db4eb

[graphite-app]

Merge activity

• Jan 14, 8:52 PM UTC: NathanFlurry added this pull request to the Graphite merge queue.
• Jan 14, 8:53 PM UTC: CI is running for this pull request on a draft pull request (#3898) due to your merge queue CI optimization settings.
• Jan 14, 8:53 PM UTC: Merged by the Graphite merge queue via draft PR: #3898.