feat: configure rivetkit storage path

[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-4233 environment in rivet-frontend

Service	Status	Web	Updated (UTC)
ladle	❌ Build Failed (View Logs)	Web	Feb 19, 2026 at 7:54 pm
website	😴 Sleeping (View Logs)	Web	Feb 19, 2026 at 7:53 pm
mcp-hub	✅ Success (View Logs)	Web	Feb 19, 2026 at 7:44 pm
frontend-cloud	❌ Build Failed (View Logs)	Web	Feb 19, 2026 at 7:44 pm
frontend-inspector	❌ Build Failed (View Logs)	Web	Feb 19, 2026 at 7:42 pm

[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

• refactor(rivetkit): add typed event and queue schemas for actors #4209 : 2 dependent PRs (#4224 , #4229 )
• feat: configure rivetkit storage path #4233 👈 (View in Graphite)
• chore(rivetkit): migrate file system driver to sqlite #4206
• main

---

How to use the Graphite Merge Queue

Add the label merge-queue to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[pkg-pr-new]

More templates

• actor-actions
• actor-actions-vercel
• ai-agent
• ai-agent-vercel
• example-ai-and-user-generated-actors-freestyle
• chat-room
• chat-room-vercel
• example-cloudflare-workers
• example-cloudflare-workers-hono
• collaborative-document
• collaborative-document-vercel
• cross-actor-actions
• cross-actor-actions-vercel
• example-cursors
• example-cursors-raw-websocket
• example-cursors-raw-websocket-vercel
• example-cursors-vercel
• custom-serverless
• custom-serverless-vercel
• example-elysia
• example-elysia-vercel
• example-experimental-durable-streams-ai-agent
• example-experimental-durable-streams-ai-agent-vercel
• geo-distributed-database
• geo-distributed-database-vercel
• hello-world
• hello-world-vercel
• example-hono
• hono-react
• hono-react-vercel
• example-hono-vercel
• example-kitchen-sink
• example-kitchen-sink-vercel
• multi-region-vercel
• multiplayer-game
• multiplayer-game-vercel
• native-websockets
• native-websockets-vercel
• next-js
• per-tenant-database
• per-tenant-database-vercel
• example-raw-fetch-handler
• example-raw-fetch-handler-vercel
• example-raw-websocket-handler
• example-raw-websocket-handler-proxy
• example-raw-websocket-handler-proxy-vercel
• example-raw-websocket-handler-vercel
• example-react
• example-react-vercel
• sandbox
• sandbox-coding-agent
• sandbox-coding-agent-vercel
• sandbox-vercel
• scheduling
• scheduling-vercel
• example-sqlite-drizzle
• example-sqlite-raw
• example-sqlite-raw-vercel
• state
• state-vercel
• example-stream
• example-stream-vercel
• example-trpc
• example-trpc-vercel

@rivetkit/cloudflare-workers

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/cloudflare-workers@4233

@rivetkit/framework-base

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/framework-base@4233

@rivetkit/next-js

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/next-js@4233

@rivetkit/react

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/react@4233

rivetkit

pnpm add https://pkg.pr.new/rivet-dev/rivet/rivetkit@4233

@rivetkit/sql-loader

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/sql-loader@4233

@rivetkit/sqlite-vfs

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/sqlite-vfs@4233

@rivetkit/traces

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/traces@4233

@rivetkit/workflow-engine

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/workflow-engine@4233

@rivetkit/virtual-websocket

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/virtual-websocket@4233

@rivetkit/engine-runner

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner@4233

@rivetkit/engine-runner-protocol

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner-protocol@4233

commit: 35e2bc0

[claude]

PR Review: feat: configure rivetkit storage path (#4233)

Summary: This PR adds a storagePath configuration option to the RegistryConfigSchema that allows users to override the default file-system storage path used by RivetKit's default driver. The value can be set programmatically via storagePath in the config object, or via the new RIVETKIT_STORAGE_PATH environment variable. When the default driver is chosen and neither an endpoint nor a token is provided, the resolved storagePath is forwarded as options.path to createFileSystemOrMemoryDriver, and logged as a structured field at debug level.

---

Code Quality and Best Practices

The implementation is clean and consistent with existing patterns. The transform pattern used for storagePath mirrors exactly how endpoint, token, and namespace already work — idiomatic and correct.

The DocRegistryConfigSchema is properly updated, keeping the documentation-generation schema in sync with the runtime schema.

The debug log in default.ts is correct — adding storagePath as a structured field is consistent with how endpoint is logged in the engine driver branch.

---

Minor Issues

1. Missing documentation update

The top of env-vars.ts contains an explicit instruction:

// IMPORTANT: When adding or modifying environment variables here, also update the
// documentation at: docs/general/registry-configuration.mdx

The PR updates environment-variables.mdx (the env-vars reference page) but does not update registry-configuration.mdx. That page may be auto-generated via the <RegistryConfigSchema> Astro component from DocRegistryConfigSchema — if so, the update is covered automatically. Worth confirming this is the case; if any sections are hand-authored, they need a mention of storagePath.

2. storagePath is silently ignored when the engine driver is used

When config.endpoint or config.token is set, chooseDefaultDriver returns the engine driver and storagePath is never consumed. There is no warning, error, or JSDoc note informing users that storagePath is a no-op in this mode. A user might configure both endpoint and storagePath and be confused by the lack of effect. Suggesting a JSDoc addition:

/**
 * Storage path for RivetKit file-system state when using the default driver.
 * Has no effect when `endpoint`, `token`, or a custom `driver` is configured.
 * Can also be set via RIVETKIT_STORAGE_PATH.
 */

---

Potential Bugs

No functional bugs identified. The wiring is correct:

• The env-var fallback in the Zod transform fires at parse time, so it correctly reads process.env.RIVETKIT_STORAGE_PATH when the registry config is parsed.
• createFileSystemOrMemoryDriver accepts options.path as string | undefined, and FileSystemGlobalState correctly falls back to getStoragePath() when customPath is undefined, so passing an undefined storagePath (when neither config nor env-var is set) is safe.
• When storagePath is an absolute path, FileSystemGlobalState uses it directly without the dirHash suffix that the default getStoragePath() adds — this is intentional and correct.

---

Performance

No performance concerns. The change is purely configuration-time wiring with no impact on hot paths.

---

Security

Path traversal is not sanitized — storagePath is accepted as a raw string and passed directly to path.join(storagePath, "state"), etc. Since this is a server-side configuration value (not user-submitted input), this is not a meaningful vulnerability in practice. No action needed.

---

Test Coverage

The two tests in registry-config-storage-path.test.ts are well-structured and cover the two primary cases:

1. RIVETKIT_STORAGE_PATH env-var is picked up when storagePath is absent from config.
2. Explicit storagePath in config overrides the env-var.

Suggested additional test case:

• Assert the baseline: when neither the config field nor the env-var is set, storagePath resolves to undefined. This would catch regressions in the default behavior cleanly.

The use of describe.sequential is appropriate since the tests mutate process.env. The finally block correctly handles the undefined case during cleanup.

---

Style and Convention Compliance

• Structured logging in default.ts correctly passes storagePath as a field key rather than interpolating it into the message string — consistent with project logging guidelines.
• No glob imports introduced.
• No new npm dependencies added.
• The Zod schema pattern (z.string().optional().transform(...)) is consistent with the pre-existing patterns for endpoint, token, and namespace in the same file.

---

Summary

This is a well-scoped, clean PR. The core implementation is correct and follows established patterns. The main actionable items are:

1. Verify that registry-configuration.mdx will automatically reflect storagePath via the DocRegistryConfigSchema component — if not, that page needs a manual update per the instruction in env-vars.ts.
2. Consider adding a JSDoc note to the storagePath field clarifying it is a no-op when endpoint, token, or driver is configured, to prevent user confusion.
3. Optional: Add a third test asserting that when neither the config field nor the env-var is set, storagePath resolves to undefined.

[graphite-app]

The storagePath field in DocRegistryConfigSchema is missing the .transform() call that exists in the main RegistryConfigSchema (lines 56-59). This inconsistency means the environment variable RIVETKIT_STORAGE_PATH will not be used as a fallback when parsing with DocRegistryConfigSchema, causing different behavior depending on which schema is used.

Fix: Add the transform to match the main schema:

storagePath: z.string().optional()
  .transform((val) => val ?? getRivetkitStoragePath())
  .describe("Storage path for RivetKit file-system state when using the default driver. Can also be set via RIVETKIT_STORAGE_PATH."),

Spotted by Graphite Agent



Is this helpful? React 👍 or 👎 to let us know.

[graphite-app]

Merge activity

• Feb 19, 10:44 PM UTC: NathanFlurry added this pull request to the Graphite merge queue.
• Feb 19, 10:44 PM UTC: CI is running for this pull request on a draft pull request (#4238) due to your merge queue CI optimization settings.
• Feb 19, 10:45 PM UTC: Merged by the Graphite merge queue via draft PR: #4238.