feat(rivetkit): allow configuring runtime mode via env

[NathanFlurry]

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

[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

• feat(rivetkit): allow configuring runtime mode via env #4866 👈 (View in Graphite)
• fix(gateway): fix protocol handling for safari #4865
• fix(rivetkit): standardize startEngine + runtime mode based on config #4851
• fix(engine): remove envoy sqlite lifecycle bookkeeping #4850
• test(rivetkit): assert force sleep websocket close reason #4849
• test(sqlite): expand db stress coverage #4846 : 1 other dependent PR (#4847 )
• test(raw-websocket): add serverless smoke coverage #4845
• feat(serverless): configure drain grace period #4844
• fix(publish): enable frontend build for engine target and use turbo build instead of turbo build:engine #4843
• feat(rivetkit): expose conn handle in onWebSocket context #4842
• fix(rivetkit): normalize waitUntil/keepAwake promises to null to avoid serde undefined error #4841
• feat(pegboard-envoy): track and close serverless sqlite actors on stop/shutdown #4840
• fix(rivetkit): remove requirement for token #4839
• fix(pegboard-envoy): allow sqlite requests across lifecycle states #4838
• fix(pegboard): route scoped actor key reads by runner dc #4837
• fix(sqlite-storage): let sqlite open take over stale owners #4834
• fix(engine-tests): parallelize multi-DC startup + enable 6 multi-DC tests #4833
• fix(api): honor cursor in actor_ids list path #4832
• fix(api): silently filter invalid IDs from actor_ids query instead of 400 #4831
• fix(api-peer): make actors_delete idempotent for already-destroyed actors #4830
• fix(pegboard): use Iterator streaming mode in list_names so limit param is honored #4829
• chore(engine-tests): convert envoy tests to Sleep crash policy + triage ignored #4828
• feat(engine-tests): wire envoy actor names through prepopulate_actor_names #4827
• main

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

[claude]

PR Review: feat(rivetkit): allow configuring runtime mode via env

Overall this is a clean, well-scoped addition that is consistent with existing codebase patterns. A few gaps worth addressing before merge.

---

Strengths

• Pattern consistency — getRivetRuntimeMode in env-vars.ts follows exactly the same shape as every other env-var accessor in that file.
• Correct precedence — config.mode is checked first; envRuntimeMode is only consulted when config.mode === undefined, preventing the env var from silently overriding deliberate programmatic config.
• Schema reuse — RuntimeModeSchema.safeParse(...) avoids duplicating the enum allowlist and correctly wires the error into Zod's issue context.
• Docs updated — the IMPORTANT header comment in env-vars.ts requires updating the docs page, and the PR does that correctly.

---

Issues / Gaps

1. Missing test: RIVET_RUNTIME_MODE=envoy with no endpoint

When RIVET_RUNTIME_MODE=envoy is set but no endpoint is configured, the existing path that fires "Rivet endpoint is required when startEngine is false" will trigger. There's already a test for the code-configured path ("explicit envoy mode requires an endpoint"), but no parallel test for the env-var path. This scenario is easy to hit by accident in a misconfigured deployment and should be covered.

2. Missing test: RIVET_RUNTIME_MODE=serverless with a valid endpoint

There's a test confirming RIVET_RUNTIME_MODE=envoy sets envoy mode, but no symmetric test for serverless. Adding it would mirror the existing pattern (e.g. "configured endpoints default to serverless" vs "explicit envoy mode disables local engine startup").

3. Confusing test setup in "explicit mode overrides RIVET_RUNTIME_MODE"

The test sets RIVET_RUNTIME_MODE=local (an invalid value) alongside mode: "envoy". The test passes because when config.mode !== undefined the env var is never parsed — so the invalid value is silently ignored rather than rejected. This is correct behavior, but a reader might not realize why it's using an intentionally invalid value. A one-line comment explaining it (e.g. // Use an invalid env value to confirm it is skipped entirely when config.mode is set) would prevent confusion.

---

Minor Nits

• The doc comment on the mode field ("Can also be set via RIVET_RUNTIME_MODE.") is consistent with how endpoint is documented. No issue.
• No performance or security concerns — env var is read once at parse time, invalid values are rejected via Zod before any runtime behavior changes.

---

Summary

The three test cases that do exist cover the core scenarios (env override, explicit wins, invalid value rejected). Adding the two missing cases and a clarifying comment would make this complete. No bugs or design issues found.

[github-actions]

Preview packages published to npm

Install with:

npm install rivetkit@pr-4866

All packages published as 0.0.0-pr.4866.1b9199c with tag pr-4866.

Engine binary is shipped via @rivetkit/engine-cli on linux-x64-musl, linux-arm64-musl, darwin-x64, and darwin-arm64. Windows users should use the release installer or set RIVET_ENGINE_BINARY.

Docker images:

docker pull rivetdev/engine:slim-1b9199c
docker pull rivetdev/engine:full-1b9199c

Individual packages

npm install rivetkit@pr-4866
npm install @rivetkit/react@pr-4866
npm install @rivetkit/rivetkit-napi@pr-4866
npm install @rivetkit/workflow-engine@pr-4866