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	😴 Sleeping (View Logs)	Web	Apr 15, 2026 at 8:50 am
website	✅ Success (View Logs)	Web	Apr 15, 2026 at 8:32 am
frontend-inspector	😴 Sleeping (View Logs)	Web	Apr 15, 2026 at 3:54 am
kitchen-sink	❌ Build Failed (View Logs)	Web	Apr 15, 2026 at 3:09 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

• chore: configure TLS trust roots for rustls clients #4667
• 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 , #4666 )
• 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]

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

Overview

This is a large refactoring PR (~4,800 additions / ~5,140 deletions) that:

1. Renames config fields from "manager" terminology to generic HTTP server terminology (managerPort → httpPort, managerBasePath → httpBasePath, etc.)
2. Moves spawnEngine/engineVersion/configureRunnerPool out of serverless nesting to top-level config (startEngine, engineVersion, configurePool)
3. Removes serveManager in favor of always starting the HTTP server via an explicit ensureHttpServer() call
4. Renames runner config key to envoy and startRunner() to startEnvoy() across docs
5. Removes deprecated @rivetkit/sqlite-native and @rivetkit/sqlite-vfs package definitions
6. Extracts the HTTP server startup into a new Runtime#ensureHttpServer() method

The changes are coherent and the refactoring is cleanly executed. Most of the diff is mechanical renaming and formatter-driven indentation changes.

---

Issues

start() hardcodes ENGINE_ENDPOINT as publicEndpoint unconditionally

In registry/index.ts, the new start() always sets serverless.publicEndpoint = ENGINE_ENDPOINT when it's not set:

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

The old code only applied the http://127.0.0.1:${managerPort} default when isDevEnv && (serveManager || spawnEngine). The new code applies ENGINE_ENDPOINT unconditionally inside start(), which is only called in the "Auto" mode. This is probably correct (since start() implies local dev), but the intent should be documented more clearly — especially since ENGINE_ENDPOINT is a constant and bypasses the dynamic port fallback path in ensureHttpServer.

start() no longer starts the local HTTP server in non-engine cases

Before this PR, calling registry.start() without an endpoint would set serveManager = true, which started the HTTP server and served the local runtime. After this PR, start() always calls ensureHttpServer() + startEnvoy(). However, the check in the Registry constructor (if (config.startEngine)) is still there, so if a user calls start() without setting startEngine: true, the preemptive warmup in the constructor is skipped. This seems intentional, but the behavior difference from the old "auto" mode (which served the local HTTP server even without an engine) is worth documenting.

Port 6420 still referenced in documentation

website/src/content/docs/actors/quickstart/backend.mdx and website/src/content/docs/general/http-server.mdx both now say:

Clients connect to the Rivet Engine on http://localhost:6420.

But the default httpPort was changed to 6421 in this PR. If the client always connects directly to the engine (port 6420), the local HTTP server's port (6421) should not be mentioned in this context at all, or the wording should be made more precise to avoid confusion.

Docs mode table still uses "Runner" label for startEnvoy()

website/src/content/docs/general/runtime-modes.mdx still labels the entry as Runner mode in the table:

| Runner | `registry.startEnvoy()` | Long-running processes without HTTP endpoints |

If the concept is being renamed from "Runner" to "Envoy", this table label should be updated too.

---

Observations

cwd fix in engine process spawning is a genuine bug fix. Changing cwd from path.dirname(binaryPath) to storageRoot is correct — the engine writes data relative to its working directory, so it should run from storageRoot, not from wherever the binary lives.

configurePool fields cleaned up correctly. Removing maxRunners, minRunners, runnersMargin, slotsPerRunner, and maxConcurrentActors from the public config schema (hardcoding them in configure.ts) is a good simplification. The // Deprecated engine fields with hardcoded defaults. comment makes the intent clear.

metadataPollInterval duplicate removed. The field was previously set twice in the configure payload — once in the inner serverless_config object and once at the top level. The duplicate top-level key is correctly removed.

DocConfigureRunnerPoolSchema → DocConfigurePoolSchema rename in the schema file is consistent with the rest of the rename.

@rivetkit/sqlite-native and @rivetkit/sqlite-vfs removal aligns with CLAUDE.md guidance to use @rivetkit/rivetkit-native. The build pipeline (publish.yaml) correctly removes the now-deleted packages from the build filter.

setupTest now explicitly calls ensureHttpServer() before checking runtime.httpPort, which is correct since create() no longer starts the HTTP server automatically.

The @ts-expect-error removal in mod.typecheck.ts (action args should be typed) should be confirmed — is this because the type check now passes (i.e., the types were fixed), or because the check was removed? If the latter, this may inadvertently drop type-safety test coverage.

---

🤖 Generated with Claude Code

[github-actions]

Preview packages published to npm

Install with:

npm install rivetkit@pr-4663

All packages published as 0.0.0-pr.4663.4a73c62 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-4a73c62
docker pull rivetdev/engine:full-4a73c62

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