Rivet Framework Documentation

Rivet Guard is the gateway service for the Rivet platform. It is responsible for handling all incoming traffic and performing two primary tasks:

• Rivet Actors Routing: Routing incoming requests to the correct Rivet Actor or Rivet Container.
• Rivet API: Routing API endpoints to the Rivet API server.

Rivet Cloud provides a managed environment for Rivet Actors with the following capabilities:

• Global Edge Network: Deploy actors to a global network to reduce latency for real-time applications with automatic scaling.
• Hybrid Cloud Integration: Works alongside your existing infrastructure on AWS, GCP, Azure, or other providers.
• Portability: Built on open-source Rivet (Apache 2.0), ensuring no vendor lock-in and full code portability.
• Enterprise Capabilities:
  • Organizations & Security: Team management and access control.
  • Multi-region Support: Deployment across multiple geographic locations.
  • FoundationDB Backend: Distributed systems with fault tolerance.
  • Observability: Built-in monitoring and debugging tools.

Rivet Workflows provides durable execution for TypeScript, built directly into Rivet Actors. It is designed to ensure that workflow progress persists across system crashes, deployments, and restarts.

Key capabilities include:

• Resilience: Automatic retries for failed steps and state persistence.
• Control Flow: Support for sleep, join, race, rollback, human-in-the-loop, and durable loops.
• Durable Agents: Ability to build AI agents with tool use, human-in-the-loop, and automatic checkpointing (compatible with the AI SDK).
• Observability: Built-in workflow inspector for debugging.
• Runtime Support: Runs on Node.js, Bun, and Cloudflare Workers under the Apache 2.0 license.

rivet-container-runner is a RivetKit (Rust) serverless app designed to host actors by spawning a child game-server process per actor and proxying Rivet's tunneled HTTP/WebSocket traffic to it.

Key behaviors:

• Each child process gets its own port.
• The process exits when the last actor stops.
• You can wrap any dedicated server (Unity, Godot, Node.js, etc.) in a container using this binary as the entrypoint to enable Rivet Compute cold-starts and routing.
• The actor input payload (CBOR-encoded) can override the child command, arguments, and environment variables per actor.
• WebSocket clients connect at the bare gateway path.
• Raw HTTP reaches the child under the /request/* prefix on the actor surface.

Depot is the per-database storage engine for Rivet's SQLite-on-FDB system. It manages FDB-backed durability, branch/fork metadata, restore points, Point-in-Time Recovery (PITR) interval bookkeeping, hot compaction, and FDB cleanup.

Note on Cold Storage: The Open Source Software (OSS) version of Depot does not include S3-backed cold storage. Any configurations attempting to specify SQLite workflow cold storage are unsupported in the OSS version.

Gasoline is the durable execution engine used for persistent tasks in Rivet Engine. It manages long-running processes through Workflows, which can be removed from memory (sleep) when inactive and reloaded from a database when needed.

Key components include:

• Workflows: Durable sequences of steps that use history replay to recover state.
• Activities: Wrappers around native functions that support automatic retries.
• Signals: Durable communication used for inter-workflow or service-to-workflow interaction.
• Messages: Ephemeral, "fire-and-forget" communication from workflows to other services.
• Operations: Thin wrappers for clean interop with the Gasoline ecosystem (Note: Operations cannot be run directly in a workflow body; they must be wrapped in an Activity first).

The ServerlessWorker is a proposed Web API (similar to Web Workers) designed to provide stateful serverless functionality. It aims to unify patterns seen in Cloudflare Durable Objects and Rivet Actors. Key characteristics include:

• Multi-Tenant: Can serve multiple clients simultaneously in real-time.
• Message-Based: Uses postMessage for communication.
• Persistent: Workers run indefinitely and can optionally sleep when inactive.
• Storage: Provides persistent data storage located near the compute for performance.
• Isolated Execution: Each worker runs in its own isolated environment.

Rivet v2.0 is a library-first architecture designed for building stateful workloads in NodeJS or Bun environments. It is composed of two primary components:

• RivetKit: The library used for building stateful workloads. The core primitive in RivetKit is the Rivet Actor.
• Rivet Engine: The orchestration layer used for self-hosting and managing actors at scale.

Because Rivet is distributed as a library, it integrates directly into your application code via standard npm installation, avoiding external service dependencies and vendor lock-in.