feat(rivetkit): download Engine and Services binaries on demand

Author: NathanFlurry

.claude/reference/dependencies.md

@@ -22,7 +22,8 @@
 - For runtime-only dependencies, use dynamic loading so bundlers do not eagerly include them.
 - Build the module specifier from string parts (for example with `["pkg", "name"].join("-")` or `["@scope", "pkg"].join("/")`) instead of a single string literal.
 - Prefer this pattern for modules like `@rivetkit/rivetkit-napi/wrapper`, `sandboxed-node`, and `isolated-vm`.
-- The TypeScript registry's native envoy path dynamically loads `@rivetkit/rivetkit-napi` and `@rivetkit/engine-cli` so browser and serverless bundles do not eagerly pull native-only modules.
+- The TypeScript registry's native envoy path dynamically loads `@rivetkit/rivetkit-napi` so browser and serverless bundles do not eagerly pull native-only modules.
+- `rivetkit` does not depend on the Engine or Services binaries. `rivetkit-engine-process::download` fetches them on demand from releases.rivet.dev at exact pinned versions, verified against `SHA256SUMS`; bump `SERVICES_VERSION` in `rivetkit-core/src/services_process.rs` to move Services.
 - If loading by resolved file path, resolve first and then import via `pathToFileURL(...).href`.
 
 ## Version bumps

.github/workflows/publish.yaml

@@ -279,6 +279,7 @@ jobs:
             --build-arg BUILD_TARGET=${{ matrix.build_target }} \
             --build-arg BUILD_MODE=${{ steps.mode.outputs.build_mode }} \
             --build-arg BUILD_FRONTEND=${{ matrix.build_target == 'engine' && 'true' || 'false' }} \
+            --build-arg RIVET_ENGINE_RELEASE_REF=${{ needs.context.outputs.trigger != 'release' && contains(needs.context.outputs.targets, 'engine') && needs.context.outputs.sha || '' }} \
             -f ${{ matrix.docker }} \
             -t builder-${{ matrix.build_target }}-${{ matrix.platform }} \
             --load \
@@ -596,19 +597,9 @@ jobs:
       - name: Finalize package versions for publish
         run: pnpm --filter=publish exec tsx src/ci/bin.ts bump-versions --version ${{ needs.context.outputs.version }}
 
-      - name: Publish npm packages
-        env:
-          # setup-node provides a dummy token value; clear it so token-only
-          # post-publish operations stay disabled for trusted publishing.
-          NODE_AUTH_TOKEN: ""
-          SKIP_WASM_BUILD: "1"
-        run: |
-          pnpm --filter=publish exec tsx src/ci/bin.ts publish-npm \
-            --tag ${{ needs.context.outputs.npm_tag }} \
-            --parallel 16 \
-            --retries 3 \
-            ${{ needs.context.outputs.trigger == 'release' && '--release-mode' || '' }}
-
+      # RivetKit downloads the Engine from releases.rivet.dev on demand, so the
+      # binaries must be published before npm. A failed upload stops the job
+      # before any npm package can point at a missing Engine.
       - name: Generate engine checksum manifest
         if: contains(needs.context.outputs.targets, 'engine')
         run: |
@@ -635,6 +626,19 @@ jobs:
             --version ${{ needs.context.outputs.version }} \
             --latest ${{ needs.context.outputs.latest }}
 
+      - name: Publish npm packages
+        env:
+          # setup-node provides a dummy token value; clear it so token-only
+          # post-publish operations stay disabled for trusted publishing.
+          NODE_AUTH_TOKEN: ""
+          SKIP_WASM_BUILD: "1"
+        run: |
+          pnpm --filter=publish exec tsx src/ci/bin.ts publish-npm \
+            --tag ${{ needs.context.outputs.npm_tag }} \
+            --parallel 16 \
+            --retries 3 \
+            ${{ needs.context.outputs.trigger == 'release' && '--release-mode' || '' }}
+
       # The Inspector UI lives in frontend/dist, outside the rivetkit-core
       # crate, so it must be built and staged into the crate before packaging.
       # Otherwise the published crate embeds the empty fallback and serves

Cargo.lock

@@ -7,6 +7,8 @@ FROM ghcr.io/rivet-dev/rivet/builder-base-osxcross:0e33ceb98
 
 ARG BUILD_TARGET=engine
 ARG BUILD_MODE=release
+# Publish commit whose Engine a preview rivetkit-napi build downloads. Empty for releases.
+ARG RIVET_ENGINE_RELEASE_REF=
 ARG BUILD_FRONTEND=false
 ARG VITE_APP_API_URL=__SAME__
 ARG VITE_FEATURE_FLAGS=

docker/build/darwin-arm64.Dockerfile

@@ -7,6 +7,8 @@ FROM ghcr.io/rivet-dev/rivet/builder-base-osxcross:0e33ceb98
 
 ARG BUILD_TARGET=engine
 ARG BUILD_MODE=release
+# Publish commit whose Engine a preview rivetkit-napi build downloads. Empty for releases.
+ARG RIVET_ENGINE_RELEASE_REF=
 ARG BUILD_FRONTEND=false
 ARG VITE_APP_API_URL=__SAME__
 ARG VITE_FEATURE_FLAGS=

docker/build/darwin-x64.Dockerfile

@@ -7,6 +7,8 @@ FROM ghcr.io/rivet-dev/rivet/builder-base-linux-gnu:0e33ceb98
 
 ARG BUILD_TARGET=engine
 ARG BUILD_MODE=release
+# Publish commit whose Engine a preview rivetkit-napi build downloads. Empty for releases.
+ARG RIVET_ENGINE_RELEASE_REF=
 ARG BUILD_FRONTEND=false
 ARG VITE_APP_API_URL=__SAME__
 ARG VITE_FEATURE_FLAGS=

docker/build/linux-arm64-gnu.Dockerfile

@@ -7,6 +7,8 @@ FROM ghcr.io/rivet-dev/rivet/builder-base-linux-musl:0e33ceb98
 
 ARG BUILD_TARGET=engine
 ARG BUILD_MODE=release
+# Publish commit whose Engine a preview rivetkit-napi build downloads. Empty for releases.
+ARG RIVET_ENGINE_RELEASE_REF=
 ARG BUILD_FRONTEND=false
 ARG VITE_APP_API_URL=__SAME__
 ARG VITE_FEATURE_FLAGS=

docker/build/linux-arm64-musl.Dockerfile

@@ -14,6 +14,8 @@ FROM ghcr.io/rivet-dev/rivet/builder-base-linux-gnu:0e33ceb98
 
 ARG BUILD_TARGET=engine
 ARG BUILD_MODE=release
+# Publish commit whose Engine a preview rivetkit-napi build downloads. Empty for releases.
+ARG RIVET_ENGINE_RELEASE_REF=
 ARG BUILD_FRONTEND=false
 ARG VITE_APP_API_URL=__SAME__
 ARG VITE_FEATURE_FLAGS=

docker/build/linux-x64-gnu.Dockerfile

@@ -7,6 +7,8 @@ FROM ghcr.io/rivet-dev/rivet/builder-base-linux-musl:0e33ceb98
 
 ARG BUILD_TARGET=engine
 ARG BUILD_MODE=release
+# Publish commit whose Engine a preview rivetkit-napi build downloads. Empty for releases.
+ARG RIVET_ENGINE_RELEASE_REF=
 ARG BUILD_FRONTEND=false
 ARG VITE_APP_API_URL=__SAME__
 ARG VITE_FEATURE_FLAGS=

docker/build/linux-x64-musl.Dockerfile

@@ -17,6 +17,8 @@ RUN apt-get update && apt-get install -y --no-install-recommends nasm && \
 
 ARG BUILD_TARGET=engine
 ARG BUILD_MODE=release
+# Publish commit whose Engine a preview rivetkit-napi build downloads. Empty for releases.
+ARG RIVET_ENGINE_RELEASE_REF=
 ARG BUILD_FRONTEND=false
 ARG VITE_APP_API_URL=__SAME__
 ARG VITE_FEATURE_FLAGS=