feat(rivetkit): RIVETKIT_RUNTIME_MODE env var, listener hardening

[abcxff]

Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[railway-app]

🚅 Deployed to the rivet-pr-5209 environment in rivet-frontend

Service	Status	Web	Updated (UTC)
ladle	🕒 Building (View Logs)	Web	Jun 9, 2026 at 3:59 pm
frontend-inspector	🕒 Building (View Logs)	Web	Jun 9, 2026 at 3:59 pm
kitchen-sink	🕒 Building (View Logs)	Web	Jun 9, 2026 at 3:59 pm
website	🕒 Building (View Logs)	Web	Jun 9, 2026 at 3:59 pm
mcp-hub	🕒 Building (View Logs)	Web	Jun 9, 2026 at 3:59 pm
frontend-cloud	🕒 Building (View Logs)	Web	Jun 9, 2026 at 3:59 pm

[abcxff]

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

• feat(rivetkit): RIVETKIT_RUNTIME_MODE env var, listener hardening #5209 👈 (View in Graphite)
• feat(rivetkit): move HTTP listener to Rust + RIVETKIT_RUNTIME_MODE env var #5132 : 1 other dependent PR (#5211 )
• main

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

[claude]

Code Review

Summary

This PR simplifies getRivetkitRuntimeMode to a single env-var check and removes the force_normal_runner_config_upsert footgun that caused runner config upserts against remote engine endpoints.

---

Breaking Change — NODE_ENV=production No Longer Implies Serverless

File: rivetkit-typescript/packages/rivetkit/src/utils/env-vars.ts

The old resolution chain was:

1. Explicit RIVETKIT_RUNTIME_MODE=envoy|serverless
2. RAILWAY_DEPLOYMENT_ID set → envoy
3. NODE_ENV=production → serverless
4. Default → envoy

The new behavior is simply: serverless if RIVETKIT_RUNTIME_MODE === "serverless", otherwise envoy.

Production deployments that relied on NODE_ENV=production to automatically select serverless mode will now silently get envoy mode — a behavioral regression. This is the most significant concern in the PR. At minimum, a migration note in the docs or a startup warning should call this out for existing users.

The Railway detection removal (RAILWAY_DEPLOYMENT_ID) is a non-issue in practice since envoy is the new default anyway.

---

Naming Improvement — ✓

Renaming ensure_normal_runner_config to ensure_local_normal_runner_config is accurate and communicates the intent well. The old name was misleading because "normal" does not convey the local-only scope.

---

force_normal_runner_config_upsert Removal — ✓

Removing the field is the right call. It was a footgun: a mode flag that could override the local-endpoint guard and cause runner config upserts against remote engines. The simplified ensure_local_normal_runner_config is correct — runner config should only be upserted when talking to a local engine.

---

Minor: Log message wording

runner_config.rs:73 — "ensured local normal runner config" is slightly awkward. "ensured local runner config" (dropping "normal") reads more cleanly. Nitpick only.

---

Tests — ✓

The test cleanup in listener.test.ts correctly reflects the new simplified logic. Each test case maps cleanly to a branch of the new one-liner. Snapshot scope is appropriately narrowed to just the one env var that matters.

---

Docs — partial

The docs update correctly removes RAILWAY_DEPLOYMENT_ID. It should also note that the production default changed: previously NODE_ENV=production implied serverless; now RIVETKIT_RUNTIME_MODE=serverless must be set explicitly. Users migrating from the old behavior currently have no signal from the docs that their config needs updating.

---

Verdict

The removal of force_normal_runner_config_upsert and the function rename are clean improvements. The main concern is the silent behavioral change for production deployments that relied on NODE_ENV=production → serverless auto-detection. That warrants a deprecation note, a startup warning, or at minimum a prominent changelog entry before this merges.