feat: configure rivetkit storage path

rivetkit-typescript/packages/rivetkit/src/drivers/default.ts

@@ -28,6 +28,11 @@ export function chooseDefaultDriver(
 		return createEngineDriver();
 	}
 
-	loggerWithoutContext().debug({ msg: "using default file system driver" });
-	return createFileSystemOrMemoryDriver(true);
+	loggerWithoutContext().debug({
+		msg: "using default file system driver",
+		storagePath: config.storagePath,
+	});
+	return createFileSystemOrMemoryDriver(true, {
+		path: config.storagePath,
+	});
 }

rivetkit-typescript/packages/rivetkit/src/registry/config/index.ts

@@ -8,6 +8,7 @@ import { tryParseEndpoint } from "@/utils/endpoint-parser";
 import {
 	getRivetEndpoint,
 	getRivetEngine,
+	getRivetkitStoragePath,
 	getRivetNamespace,
 	getRivetToken,
 	isDev,
@@ -45,6 +46,17 @@ export const RegistryConfigSchema = z
 
 		// MARK: Driver
 		driver: DriverConfigSchema.optional(),
+		/**
+		 * Storage path for RivetKit file-system state when using the default driver.
+		 *
+		 * If not set, RivetKit uses the platform default data location.
+		 *
+		 * Can also be set via RIVETKIT_STORAGE_PATH.
+		 */
+		storagePath: z
+			.string()
+			.optional()
+			.transform((val) => val ?? getRivetkitStoragePath()),
 
 		// MARK: Networking
 		/** @experimental */
@@ -331,6 +343,7 @@ export const DocRunnerConfigSchema = z.object({
 export const DocRegistryConfigSchema = z
 	.object({
 		use: z.record(z.string(), z.unknown()).describe("Actor definitions. Keys are actor names, values are actor definitions."),
+		storagePath: z.string().optional().describe("Storage path for RivetKit file-system state when using the default driver. Can also be set via RIVETKIT_STORAGE_PATH."),
 		maxIncomingMessageSize: z.number().optional().describe("Maximum size of incoming WebSocket messages in bytes. Default: 65536"),
 		maxOutgoingMessageSize: z.number().optional().describe("Maximum size of outgoing WebSocket messages in bytes. Default: 1048576"),
 		noWelcome: z.boolean().optional().describe("Disable the welcome message on startup. Default: false"),

rivetkit-typescript/packages/rivetkit/src/utils/env-vars.ts

@@ -44,6 +44,8 @@ export const getRivetkitInspectorToken = (): string | undefined =>
 	getEnvUniversal("RIVET_INSPECTOR_TOKEN");
 export const getRivetkitInspectorDisable = (): boolean =>
 	getEnvUniversal("RIVET_INSPECTOR_DISABLE") === "1";
+export const getRivetkitStoragePath = (): string | undefined =>
+	getEnvUniversal("RIVETKIT_STORAGE_PATH");
 
 // Logging configuration
 // DEPRECATED: LOG_LEVEL will be removed in a future version

rivetkit-typescript/packages/rivetkit/tests/registry-config-storage-path.test.ts

@@ -0,0 +1,41 @@
+import { RegistryConfigSchema } from "@/registry/config";
+import { describe, expect, test } from "vitest";
+
+describe.sequential("registry config storagePath", () => {
+	test("reads storagePath from RIVETKIT_STORAGE_PATH when unset in config", () => {
+		const previous = process.env.RIVETKIT_STORAGE_PATH;
+		try {
+			process.env.RIVETKIT_STORAGE_PATH = "/tmp/rivetkit-storage-env";
+			const parsed = RegistryConfigSchema.parse({
+				use: {},
+			});
+
+			expect(parsed.storagePath).toBe("/tmp/rivetkit-storage-env");
+		} finally {
+			if (previous === undefined) {
+				delete process.env.RIVETKIT_STORAGE_PATH;
+			} else {
+				process.env.RIVETKIT_STORAGE_PATH = previous;
+			}
+		}
+	});
+
+	test("config storagePath overrides RIVETKIT_STORAGE_PATH", () => {
+		const previous = process.env.RIVETKIT_STORAGE_PATH;
+		try {
+			process.env.RIVETKIT_STORAGE_PATH = "/tmp/rivetkit-storage-env";
+			const parsed = RegistryConfigSchema.parse({
+				use: {},
+				storagePath: "/tmp/rivetkit-storage-config",
+			});
+
+			expect(parsed.storagePath).toBe("/tmp/rivetkit-storage-config");
+		} finally {
+			if (previous === undefined) {
+				delete process.env.RIVETKIT_STORAGE_PATH;
+			} else {
+				process.env.RIVETKIT_STORAGE_PATH = previous;
+			}
+		}
+	});
+});

website/src/content/docs/general/environment-variables.mdx

@@ -45,6 +45,12 @@ These variables configure how clients connect to your actors.
 | `RIVET_INSPECTOR_TOKEN` | Token for accessing the Rivet Inspector |
 | `RIVET_INSPECTOR_DISABLE` | Set to `1` to disable the inspector |
 
+## Storage
+
+| Environment Variable | Description |
+|---------------------|-------------|
+| `RIVETKIT_STORAGE_PATH` | Overrides the default file-system storage path used by RivetKit when using the default driver. |
+
 ## Logging
 
 | Environment Variable | Description |
@@ -55,4 +61,3 @@ These variables configure how clients connect to your actors.
 | `RIVET_LOG_MESSAGE` | Set to `1` to include message formatting |
 | `RIVET_LOG_ERROR_STACK` | Set to `1` to include error stack traces |
 | `RIVET_LOG_HEADERS` | Set to `1` to log request headers |
-