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

.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

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-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/linux-arm64-gnu.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-musl.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-gnu.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-musl.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/windows-x64.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=

docs/actors/content/docs/quickstart/rust.mdx

@@ -127,18 +127,18 @@ Replace `counter` with your crate name (the package `name` in `Cargo.toml`, with
 
 <Step title="Run The Server">
 
-The Rust runtime connects to the Rivet control plane. Setting `RIVETKIT_ENGINE_AUTO_DOWNLOAD=1` lets the runtime download and cache a matching engine binary the first time you run, so there is nothing else to install:
+The Rust runtime connects to the Rivet control plane. The first time you run, it downloads and caches a matching engine binary and the Rivet Services binary, so there is nothing else to install:
 
 ```sh
-RIVETKIT_ENGINE_AUTO_DOWNLOAD=1 cargo run
+cargo run
 ```
 
 Your server now connects to the Rivet control plane on `http://localhost:6420`. Clients connect directly to the control plane on this port.
 
 Visit [http://localhost:6420](http://localhost:6420) in your browser (or point your AI agent at it) to open the Rivet developer tools and inspect your actors live.
 
 <Note>
-Already have a control plane binary? Set `RIVET_ENGINE_BINARY_PATH=/path/to/rivet-engine` to point at it instead. If you are working inside the [Rivet monorepo](https://github.com/rivet-dev/rivet), a local `cargo build -p rivet-engine` is discovered automatically from `target/debug`.
+Already have a control plane binary? Set `RIVET_ENGINE_BINARY_PATH=/path/to/rivet-engine` to point at it instead. Set `RIVET_RUN_SERVICES=0` to run without Services, or `RIVET_DISABLE_BINARY_DOWNLOAD=1` to turn off downloads. If you are working inside the [Rivet monorepo](https://github.com/rivet-dev/rivet), a local `cargo build -p rivet-engine` is discovered automatically from `target/debug`.
 </Note>
 
 </Step>

docs/api/error-registry.json

@@ -579,16 +579,6 @@
 					"message": "Engine binary is unavailable.",
 					"statuses": []
 				},
-				{
-					"code": "checksum_mismatch",
-					"message": "Engine binary checksum mismatch.",
-					"statuses": []
-				},
-				{
-					"code": "download_failed",
-					"message": "Engine binary download failed.",
-					"statuses": []
-				},
 				{
 					"code": "health_check_failed",
 					"message": "Engine health check failed.",

docs/general/content/cli.mdx

@@ -153,7 +153,7 @@ By default the namespace must already exist. Pass `--create-namespace` to create
 
 ## Engine binary resolution
 
-`rivet dev` and `rivet engine` resolve the `rivet-engine` binary from, in order: `--engine-binary`, `RIVET_ENGINE_BINARY_PATH`, a binary bundled next to the CLI, a local `target/{debug,release}` build, then an auto-downloaded release. Set `RIVETKIT_ENGINE_AUTO_DOWNLOAD=0` to require a local binary.
+`rivet dev` and `rivet engine` resolve the `rivet-engine` binary from, in order: `--engine-binary`, `RIVET_ENGINE_BINARY_PATH`, a binary bundled next to the CLI, a local `target/{debug,release}` build, then an auto-downloaded release. The downloaded release matches the CLI version unless `RIVET_RUN_ENGINE_VERSION` names an exact version. Set `RIVET_DISABLE_BINARY_DOWNLOAD=1` to require a local binary.
 
 ## Related
 

docs/general/content/environment-variables.mdx

@@ -40,8 +40,16 @@ These variables configure how clients connect to your actors.
 | Environment Variable | Description |
 |---------------------|-------------|
 | `RIVET_RUN_ENGINE` | Set to `1` to spawn the control plane process |
-| `RIVET_RUN_ENGINE_HOST` | Host to bind the spawned local engine process to. Defaults to `127.0.0.1`. |
-| `RIVET_RUN_ENGINE_PORT` | Port to bind the spawned local engine process to. Defaults to `6420`. |
-| `RIVET_RUN_ENGINE_VERSION` | Version of engine to download |
-| `RIVET_RUN_SERVICES` | Set to `1` to run Services with a local Engine, or `0` to disable it. By default, Services follows RivetKit's local-Engine decision. |
-| `RIVET_SERVICES_BINARY` | Path to a local `rivet-services` binary. |
+| `RIVET_RUN_ENGINE_HOST` | Host to bind the spawned local engine process to. Defaults to the host of the local endpoint (`127.0.0.1`). |
+| `RIVET_RUN_ENGINE_PORT` | Port to bind the spawned local engine process to. Defaults to the port of the local endpoint (`6420`). |
+| `RIVET_RUN_ENGINE_VERSION` | Exact Engine version to download for local development, such as `2.3.30`. Defaults to the installed RivetKit version. Aliases such as `latest` are rejected. `RIVETKIT_ENGINE_VERSION` is a deprecated alias. |
+| `RIVET_RUN_SERVICES` | Set to `1` to run Services with a local Engine, or `0` to disable it. Services runs by default whenever RivetKit runs a local Engine. Without an explicit `1`, platforms without a Services build (such as Alpine) run without it after a warning. |
+| `RIVET_ENGINE_BINARY_PATH` | Path to a local `rivet-engine` binary. Skips the download. |
+| `RIVET_SERVICES_BINARY` | Path to a local `rivet-services` binary. Skips the download. |
+| `RIVET_DISABLE_BINARY_DOWNLOAD` | Set to `1` to never download the Engine or Services binaries, for offline or locked-down environments. Provide the binaries with the variables above instead. Overrides every other download setting. |
+| `RIVETKIT_ENGINE_AUTO_DOWNLOAD` | Set to `0` to stop downloading binaries that are not already cached. Defaults to `1`. |
+| `RIVET_BINARY_CACHE_DIR` | Directory for downloaded binaries. Defaults to the user cache directory (`$XDG_CACHE_HOME/rivet` or `~/.cache/rivet` on Linux, `~/Library/Caches/rivet` on macOS, `%LOCALAPPDATA%\rivet` on Windows). |
+
+When RivetKit runs a local Engine for development, it downloads the Engine that matches your RivetKit version and the Services release pinned by it from `releases.rivet.dev` on first use, verifies their SHA-256 checksums, and caches them for later runs. Nothing is downloaded when `RIVET_ENDPOINT` points at a remote Engine.
+
+TypeScript and Rust apps resolve these variables the same way. A value set in code (such as `engineVersion`, `startServices`, `engineHost`, or `enginePort` in the TypeScript registry config) takes precedence over its environment variable, which takes precedence over the default.

docs/integrations/content/docs/vercel-eve.mdx

@@ -64,7 +64,6 @@ export default defineAgent({
 			"@rivet-dev/agentos-runtime-core",
 			"@rivet-dev/agentos-sidecar",
 			"@rivet-dev/workflow-world",
-			"@rivetkit/engine-cli",
 		],
 	},
 	experimental: {

engine/packages/cli/src/engine_runner.rs

@@ -29,13 +29,10 @@ pub fn engine_config(engine_binary: Option<PathBuf>) -> EngineResolverConfig {
 }
 
 /// Whether the CLI may download a release engine binary when none is found
-/// locally. Enabled by default for the CLI; set `RIVETKIT_ENGINE_AUTO_DOWNLOAD`
-/// to `0` or `false` to require a local binary.
+/// locally. Enabled by default for the CLI; set `RIVET_DISABLE_BINARY_DOWNLOAD=1`
+/// or `RIVETKIT_ENGINE_AUTO_DOWNLOAD=0` to require a local binary.
 fn engine_auto_download() -> bool {
-	match env::var("RIVETKIT_ENGINE_AUTO_DOWNLOAD") {
-		Ok(value) => !matches!(value.trim(), "0" | "false" | ""),
-		Err(_) => true,
-	}
+	rivetkit_engine_process::download::auto_download_from_env(true)
 }
 
 /// Path to a rivet-engine binary distributed next to this CLI binary.

rivetkit-rust/engine/artifacts/errors/binary_download.checksum_mismatch.json

@@ -0,0 +1,5 @@
+{
+  "code": "checksum_mismatch",
+  "group": "binary_download",
+  "message": "Binary checksum mismatch."
+}

rivetkit-rust/engine/artifacts/errors/binary_download.checksum_missing.json

@@ -0,0 +1,5 @@
+{
+  "code": "checksum_missing",
+  "group": "binary_download",
+  "message": "Binary checksum is missing from the release manifest."
+}

rivetkit-rust/engine/artifacts/errors/binary_download.disabled.json

@@ -0,0 +1,5 @@
+{
+  "code": "disabled",
+  "group": "binary_download",
+  "message": "Binary downloads are disabled."
+}

rivetkit-rust/engine/artifacts/errors/binary_download.http_status.json

@@ -0,0 +1,5 @@
+{
+  "code": "http_status",
+  "group": "binary_download",
+  "message": "Binary download returned an HTTP error."
+}

rivetkit-rust/engine/artifacts/errors/binary_download.incomplete.json

@@ -0,0 +1,5 @@
+{
+  "code": "incomplete",
+  "group": "binary_download",
+  "message": "Binary download was incomplete."
+}

rivetkit-rust/engine/artifacts/errors/binary_download.invalid_version.json

@@ -0,0 +1,5 @@
+{
+  "code": "invalid_version",
+  "group": "binary_download",
+  "message": "Binary version is invalid."
+}

rivetkit-rust/engine/artifacts/errors/binary_download.io.json

@@ -0,0 +1,5 @@
+{
+  "code": "io",
+  "group": "binary_download",
+  "message": "Binary cache could not be written."
+}

rivetkit-rust/engine/artifacts/errors/binary_download.lock_timeout.json

@@ -0,0 +1,5 @@
+{
+  "code": "lock_timeout",
+  "group": "binary_download",
+  "message": "Timed out waiting for another binary download."
+}