docs: improve sleeping and actor lifecycle documentation

[NathanFlurry]

Summary

Reorganizes and simplifies the actor sleeping and shutdown documentation to be more concise and actionable. Removes deprecated APIs and clarifies best practices for managing actor sleep and shutdown.

Changes

• Removed deprecated c.keepAwake(promise) section and related references
• Deprecated options.noSleep in favor of c.setPreventSleep(true) in onWake
• Renamed "Forced Shutdown (Version Deploys)" section to "Actor Migration" with brief intro covering version upgrades and serverless timeouts
• Consolidated shutdown sequence documentation — reduced from 6 steps to 5, removed redundant explanations
• Removed nested onSleep and c.waitUntil subsections, streamlining the sleeping section
• Added recommendation to use c.waitUntil() for critical action work that must complete before shutdown
• Reorganized sleeping section: moved Sleep Timeouts before Sleep Shutdown Sequence for better flow
• Linked sleep timeouts to the options documentation
• Updated related docs: added waitUntilTimeout to options reference, limits, versions, and architecture pages

Type of change

• This change requires a documentation update

[railway-app]

🚅 Deployed to the rivet-pr-4472 environment in rivet-frontend

Service	Status	Web	Updated (UTC)
frontend-cloud	😴 Sleeping (View Logs)	Web	Mar 21, 2026 at 8:36 pm
frontend-inspector	😴 Sleeping (View Logs)	Web	Mar 21, 2026 at 8:34 pm
mcp-hub	✅ Success (View Logs)	Web	Mar 21, 2026 at 8:24 pm
website	❌ Build Failed (View Logs)	Web	Mar 21, 2026 at 8:23 pm
ladle	❌ Build Failed (View Logs)	Web	Mar 21, 2026 at 8:06 pm

[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
• example-elysia
• 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-kitchen-sink
• example-kitchen-sink-vercel
• multi-region-vercel
• multiplayer-game
• example-multiplayer-game-patterns
• example-multiplayer-game-patterns-vercel
• 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
• state
• state-vercel
• example-stream
• example-stream-vercel
• example-trpc

@rivetkit/virtual-websocket

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

@rivetkit/cloudflare-workers

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

@rivetkit/framework-base

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

@rivetkit/next-js

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

@rivetkit/react

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

rivetkit

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

@rivetkit/sql-loader

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

@rivetkit/sqlite-vfs

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

@rivetkit/traces

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

@rivetkit/workflow-engine

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

@rivetkit/engine-runner

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

@rivetkit/engine-runner-protocol

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

commit: 4ae37ca

[claude]

PR Review: docs: improve sleeping and actor lifecycle documentation

This is a good PR that improves documentation organization and fixes a real behavioral bug. Here are the issues found:

---

Bug: noSleep Indentation in config.ts

The deprecated JSDoc comment and the noSleep property have mismatched indentation (lines 221-222). The comment is at 3 tabs of indentation but the noSleep: z.boolean()... line on the next line is at only 2 tabs, while all surrounding properties are at 3 tabs. This will be caught by the formatter but should be fixed before merging.

---

OpenAPI Spec / Implementation Mismatch

The PR removes /gateway/{actorId}/inspector/database/schema and /gateway/{actorId}/inspector/database/rows from rivetkit-openapi/openapi.json, but both endpoints still exist in the router implementation at rivetkit-typescript/packages/rivetkit/src/actor/router.ts lines 292 and 301.

Per the CLAUDE.md guidelines, the HTTP inspector and its spec should stay in sync. If the intent is to remove these endpoints from the spec, the corresponding router routes and any driver tests should also be removed. If this is intentional deferral, a comment explaining why would help.

---

Sitemap Entry Commented Out Instead of Deleted

website/src/sitemap/mod.ts comments out the Sandbox Actor entry rather than removing it. Dead commented-out code in a sitemap creates confusion about intent. Either remove it fully or add a comment explaining when it will return.

---

Positive Notes

• Behavioral fix in instance/mod.ts is correct and well-validated by the new test: moving #disconnectConnections() after #waitBackgroundPromises() ensures waitUntil callbacks can still send events to connected clients before those connections are torn down. The new sleepWithWaitUntilMessage fixture and test case directly verify this behavior.
• Shutdown sequence documentation now accurately reflects the updated code order (waitUntil then disconnect then save).
• architecture.mdx fix from options.onSleepTimeout to options.sleepTimeout is a correct bug fix.
• waitUntilTimeout documentation is consistently added across lifecycle.mdx, limits.mdx, and versions.mdx.