fix(rivetkit): update config to match envoys & remove manager references

[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

[railway-app]

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

Service	Status	Web	Updated (UTC)
frontend-cloud	✅ Success (View Logs)	Web	Apr 15, 2026 at 2:51 am
frontend-inspector	✅ Success (View Logs)	Web	Apr 15, 2026 at 2:51 am
kitchen-sink	❌ Build Failed (View Logs)	Web	Apr 15, 2026 at 2:50 am
website	😴 Sleeping (View Logs)	Web	Apr 15, 2026 at 2:34 am
mcp-hub	✅ Success (View Logs)	Web	Apr 15, 2026 at 2:25 am
ladle	✅ Success (View Logs)	Web	Apr 15, 2026 at 1:23 am

[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

• fix(rivetkit): update config to match envoys & remove manager references #4663 👈 (View in Graphite)
• chore(publish): pin docker base image refs #4652
• chore(engine): publish engine bases in ci #4649 : 2 other dependent PRs (#4650 , #4659 )
• chore: lockfile lefthook #4647
• fix(rivetkit): surface native sqlite kv errors to callers #4645
• fix(rivetkit): prevent sleep races during disconnect and db work #4644
• fix(rivetkit): isolate engine envoys and propagate startup failures #4643
• test(rivetkit): remove wasm sqlite-only fixtures and coverage #4642
• chore(sqlite-vfs): remove wasm sqlite packages and workspace wiring #4641
• chore(rivetkit): remove wasm sqlite runtime #4614
• fix(sqlite-native): restore native startup kv preload #4639
• fix(sqlite-native): delete metadata before chunk range #4638
• fix(sqlite-native): keep truncate cache coherent #4637
• fix(sqlite-vfs): use delete range for truncate cleanup #4636
• fix(sqlite-native): restore kv error hook #4635
• perf(sqlite-native): avoid cloning cached read chunks #4634
• perf(sqlite-native): gate kv operation labels #4633
• perf(sqlite-native): reuse read cache for partial writes #4632
• perf(sqlite-native): remove delete file existence probe #4631
• fix(sqlite-native): gate native read cache behind env var #4630
• fix(pegboard): isolate runner config dc lookup failures #4625 : 1 other dependent PR (#4626 )
• docs(pegboard): note runner config upsert split write risk #4624
• fix(pegboard): unpack global runner config keys correctly #4623
• fix(pegboard-gateway): enforce tunnel message state #4622
• fix(pegboard-runner): clear terminal tunnel routes #4621
• fix(pegboard): skip protocol version keys in runner pool backfill #4620
• fix(pegboard): create missing normal runner configs #4619
• fix(epoxy): reuse cached optimistic value #4618
• main

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

[claude]

Code Review: fix(rivetkit): update config to match envoys & remove manager references

Overview

This PR renames/refactors the RivetKit config API to align with "envoy" terminology, flattens previously nested config fields, removes deprecated @rivetkit/sqlite-native and @rivetkit/sqlite-vfs packages, makes the HTTP server lazy-start, and updates docs throughout.

---

Issues

1. Stale port in docs after default port change (6420 → 6421)

website/src/content/docs/actors/quickstart/backend.mdx and website/src/content/docs/general/http-server.mdx both still mention http://localhost:6420 after the default was bumped to 6421. These will mislead new users.

2. requestLifespan unit description changed without migration guidance

The JSON schema description changed from "milliseconds" (old) to "seconds" (new). The TypeScript code already uses seconds (15 * 60 = 900). If the old description was wrong and the code always used seconds, this is a doc fix only — but users who followed the old description and passed milliseconds (e.g. 900_000) will silently get a 1000x larger timeout. Worth calling out in the PR or changelog.

3. registry.start() guard condition may not work as intended

In rivetkit-typescript/packages/rivetkit/src/registry/index.ts:

if (this.#config.serverless.publicEndpoint === undefined) {
    this.#config.serverless.publicEndpoint = ENGINE_ENDPOINT;
}

ServerlessConfigSchema may already apply a default to publicEndpoint, meaning after parsing the value won't be undefined even if the user never set it. Worth verifying the guard matches the actual runtime state post-parsing.

4. Missing newline at end of JSON schema files

Both rivetkit-json-schema/registry-config.json and rivetkit-typescript/artifacts/registry-config.json now end without a trailing newline. Minor hygiene issue causing unnecessary diff noise.

5. Test file still references old 6420 port

The driver test variants file has a hardcoded fallback:

const endpoint = process.env.RIVET_ENDPOINT || "http://127.0.0.1:6420";

Should be updated to 6421 (or reference a shared constant) to avoid tests silently connecting to the wrong port when RIVET_ENDPOINT is unset.

---

Observations

Breaking changes are not flagged — all config renames (serveManager, managerPort, managerBasePath, managerHost, publicDir, serverless.spawnEngine, serverless.engineVersion, serverless.configureRunnerPool, runner/runnerName/runnerKey) are hard breaks with no backward-compat shims. The RIVET_RUNNER_VERSION → RIVET_ENVOY_VERSION env var rename is similarly hard. If this is an intentional semver major bump, it should be noted in the PR description so reviewers and release tooling know.

Flattening configurePool and engine fields is a clear improvement — the old nesting inside serverless was confusing for settings that affect the local engine.

Lazy ensureHttpServer() is a good pattern change. Separating it from Runtime.create() avoids unconditionally binding a port in serverless mode.

Hardcoded deprecated fields in configure.ts — max_runners, min_runners, runners_margin, slots_per_runner are now hardcoded with a comment "Deprecated engine fields with hardcoded defaults." Clarifying whether these are deprecated by the engine API or by RivetKit config would help future readers.

Formatting-only churn — the bulk of the diff (especially engine-runner-protocol/src/index.ts, websocket-tunnel-adapter.ts, tunnel.ts) is purely reformatting (4-space to tabs, adding semicolons). Mixing cosmetic reformats with semantic changes makes the diff harder to review.

Docs runtime-modes table still has "Runner" in the row header while the method is now registry.startEnvoy(). Minor inconsistency worth a one-word fix.

---

Summary

The config API cleanup is directionally correct and improves clarity. Main things to address before merge: stale 6420 port references in docs, verifying the publicEndpoint guard condition, missing trailing newlines in the JSON schema files, and the stale port in the test fallback. The breaking nature of the renames should be surfaced in the PR description or changelog.

[github-actions]

Preview packages published to npm

Install with:

npm install rivetkit@pr-4663

All packages published as 0.0.0-pr.4663.e516712 with tag pr-4663.

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-e516712
docker pull rivetdev/engine:full-e516712

Individual packages

npm install rivetkit@pr-4663
npm install @rivetkit/react@pr-4663
npm install @rivetkit/rivetkit-native@pr-4663
npm install @rivetkit/workflow-engine@pr-4663