Summary

• allow startEngine: true to use an explicit local endpoint, so local engines can bind to non-default ports
• keep rejecting startEngine with remote endpoints
• classify any local endpoint as local/native in runtime logging and open devtools against the configured endpoint instead of hardcoded localhost:6420
• document RIVET_ENDPOINT as the way to select the spawned local engine port when RIVET_RUN_ENGINE=1

User stories

• As a developer running multiple local app checkouts, I can start each checkout with its own Rivet engine port instead of all colliding on 6420.
• As a RivetKit user, I can still rely on startEngine being local-only; remote endpoints remain rejected when trying to spawn a local engine.
• As a devtools user, opening devtools follows the configured local engine endpoint rather than assuming the default port.

Why this approach

• The Rust engine already derives bind ports from the configured endpoint; the TypeScript config validation/defaulting was the blocker.
• Reusing RIVET_ENDPOINT keeps the public surface small and avoids overloading generic app PORT variables.
• The local-endpoint helper centralizes the distinction between local native and remote endpoints for validation and logging.
• Concurrent local engines also need separate storage roots because RocksDB takes an exclusive lock; this is documented via RIVETKIT_STORAGE_PATH.

Validation

• git diff --check
• pnpm --filter rivetkit run check-types
• pnpm --filter rivetkit run build
• pnpm --filter @rivetkit/rivetkit-napi run build:force
• cargo build -p rivet-engine
• Smoke tested examples/hello-world with RIVET_RUN_ENGINE=1, RIVET_ENDPOINT=http://127.0.0.1:7654, RIVET_ENGINE_BINARY=/Users/hamish/Developer/rivet/target/debug/rivet-engine, and an isolated RIVETKIT_STORAGE_PATH while another engine was already listening on 6420:
  • lsof showed rivet-engine listening on 127.0.0.1:7654, 7655, and 7664
  • curl http://127.0.0.1:7654/health returned {"runtime":"engine","status":"ok","version":"2.3.0-rc.12"}
  • a rivetkit/client call to the hello-world counter actor returned increment 2 and count 2
• pnpm --filter rivetkit exec vitest run tests/registry-constructor.test.ts partially ran: the new tests passed, but the existing "reads config mutations made before the native registry is built" test is blocked in this checkout by missing @rivetkit/rivetkit-napi-darwin-arm64 until the local NAPI artifact is built.

Notes

• Direct push to rivet-dev/rivet was denied for my GitHub account, so this PR is opened from the hami-sh/rivet fork.