rivet-dev/skills

Overview

This skill provides practical guidance for building, modifying, debugging, and deploying Rivet Actors and RivetKit backends. It focuses on actor lifecycle, state vs vars, connections, queues, and runtime modes (serverless vs runner). Use it to accelerate development of long-lived, in-memory actor processes and to troubleshoot running actors.

How this skill works

The skill explains how to define actors, registries, and expose handlers or runners (registry.serve(), registry.handler(), registry.startRunner()). It covers inspection via the gateway inspector HTTP API, persistence rules (c.state, c.kv, c.db), ephemeral vars (c.vars), connections, events, and actions. It also walks through local verification, deployment choices, and debugging steps to collect reproducible reports for Discord or GitHub support.

When to use it

• When you need long-lived in-memory processes that retain state between requests.
• When HTTP endpoints or standard databases introduce latency or complexity for realtime systems.
• While building multiplayer, realtime collaboration, or workflow orchestration.
• When you must persist structured or unbounded data with clear storage boundaries.
• When debugging running actors, inspecting state, connections, or trace spans.

Best practices

• Prefer serverless mode (registry.handler/serve) unless you have a specific runner requirement.
• Fail fast by default; only add try/catch for real recovery, cleanup, or actionable context.
• Never store durable data in c.vars — use c.state for small blobs, c.kv for unbounded key-value, and c.db for SQL needs.
• Use compound array keys for actor identities to avoid key injection via string interpolation.
• Verify /api/rivet/metadata returns 200 in local dev before deploying.

Example use cases

• AI agent sandboxes that need multi-step memory and durable toolchains.
• Shared collaborative documents, cursors, or chat with real-time broadcasts.
• Durable workflow queues and background jobs with backpressure control.
• Geo-distributed, per-tenant caches or sharded database frontends.
• WebSocket servers or custom protocol endpoints requiring low-latency state access.