Getting Started

Rivet Actors

Rivet Actors allows you to deploy resilient, stateful services that maintain their state between requests. Use them for websocket servers, game backends, real-time collaboration services, and more.

Get Started Faster With ActorCore

For getting started quickly using JavaScript, we recommend trying ActorCore – our full-stack framework for working with Rivet Actors.

What are actors good for?

Stateful Services: Applications where maintaining state across interactions is critical. For example, Collaborative Apps with shared editing and automatic persistence.
Realtime Systems: Applications requiring fast, in-memory state modifications or push updates to connected clients. For example, Multiplayer Games with game rooms and player state.
Long-Running Processes: Tasks that execute over extended periods or in multiple steps. For example, AI Agents with ongoing conversations and stateful tool calls.
Durability: Processes that must survive crashes and restarts without data loss. For example, Durable Execution workflows that continue after system restarts.
Horizontal Scalability: Systems that need to scale by distributing load across many instances. For example, Realtime Stream Processing for stateful event handling.
Local-First Architecture: Systems that synchronize state between offline clients. For example, Local-First Sync between devices.

Quickstart

Step 1: Writing an actor

Add the @rivet-gg/actor package to your project for comprehensive TypeScript definitions:

Command Line

npm install -S @rivet-gg/actor

This package is optional

You can use Rivet actors without this package, but you'll need to define your own types.

Every actor must export a default object with an async start function. Here's a simple HTTP server example:

src/index.ts

import type { ActorContext } from "@rivet-gg/actor";
import { Hono } from "hono";

export default {
  async start(ctx: ActorContext) {
    const port = parseInt(Deno.env.get("PORT_HTTP") || "8080");
    console.log(`HTTP server running on port ${port}`);
    
    const app = new Hono();
    
    app.get("/", (c) => {
      return c.text(`Hello from Rivet Actor ${ctx.metadata.actor.id} running in ${ctx.metadata.region.id}!`);
    });
    
    Deno.serve({ port }, app.fetch);
    
    // Keep the actor running until explicitly destroyed
    await new Promise((resolve) => {});
  }
};

What this code does:

Creates a simple HTTP server using Hono with Deno
Sets up a route that returns the actor ID and region information
Keeps the actor running indefinitely by returning a promise that never resolves

Using classes

You can also use a class with a static method for your entrypoint:

src/index.ts

import type { ActorContext } from "@rivet-gg/actor";

export default class MyActor {
  static async start(ctx: ActorContext) {
	// Your HTTP server implementation would go here
  }
}

Step 2: Deploying an actor

Specify the script in your rivet.json:

rivet.json

{
  "actors": {
    "my-actor": {
      "script": "./src/index.ts"
    }
  }
}

Now deploy your actor with:

Command Line

rivet deploy

Step 3: Starting an actor

In this step, you're requesting Rivet to launch your actor code in the cloud:

TypeScript

import { RivetClient } from "@rivet-gg/api";

// Initialize the Rivet client with your API token
// You can get this from the Rivet dashboard
const client = new RivetClient({
  token: process.env.RIVET_TOKEN
});

// Create an actor - this launches your code on Rivet's infrastructure
const { actor } = await client.actors.create({
  // Your project and environment IDs from the Rivet dashboard
  project: "your-project-id",
  environment: "your-environment-id",
  body: {
    // Tags help identify this specific actor instance
    // You can query actors by these tags later
    tags: { name: "my-actor" },
    
    // buildTags determine which actor code to run
    // This should match tags in your rivet.json build configuration
    // The current tag is automatically assigned on deploy
    buildTags: { name: "my-actor", current: "true" },
    
    // Network configuration for your actor
    network: {
      ports: {
        http: {
          // The protocol used for communication
          protocol: "https",
        }
      }
    },
    
    // Optional: Specify a region for lower latency to specific users
    // If not specified, Rivet will choose the optimal region
    // region: "atl",
  }
});

// The actor.id is a unique identifier for this actor instance
console.log("Created actor:", actor.id);

What happens during creation:

Rivet finds the latest build matching your buildTags
It provisions resources in the specified region (or chooses the best one)
It starts your actor code with the provided environment variables
The actor starts running and initializes based on your code's start function

See actors.create for more options.

Step 4: Connecting to an actor

Once your actor is running, you can access its URL directly from the actor object:

TypeScript

// The actor response includes the URL information
// You can access it for any port you configured
const httpUrl = actor.network.ports.http.url;

// The URL is a public endpoint to your actor
console.log("Actor HTTP URL:", httpUrl);

// Use the URL to communicate with your actor
// In this example, we're calling the /hello endpoint on our HTTP server
const response = await fetch(`${httpUrl}/hello`);
const text = await response.text();
console.log("Response from actor:", text);

What happens during connection:

Each port configured for your actor gets a unique URL
These URLs are accessible based on your actor's security settings
The URL routes to your actor regardless of which region it's in
For additional security, you can use getConnection to generate temporary, authenticated URLs

See actors.get for more details.

Step 5: Destroying an actor

When you're finished using the actor, it's important to destroy it to free up resources:

TypeScript

// Destroy the actor to free up resources and stop billing
await client.actors.destroy(actor.id, {
  project: "your-project-id",
  environment: "your-environment-id",
});

console.log("Actor destroyed");

What happens during destruction:

Rivet sends a termination signal to your actor
Your actor gets a short grace period to clean up resources
All compute resources associated with the actor are freed
You stop being billed for the actor's runtime

See actors.destroy for more details.

Note

Always destroy actors when you're done with them to avoid unnecessary costs. Actors will continue running and billing will continue until explicitly destroyed.

Configuration

See the configuration documentation for all available options.

The `ActorContext` Object

Your start function receives an ActorContext object with important metadata and services:

TypeScript

interface ActorContext {
  // Information about your actor and its environment
  metadata: {
    actor: {
      id: string;
      tags: Record<string, string>;
      createdAt: Date;
    };
    project: {
      id: string;
      slug: string;
    };
    environment: {
      id: string;
      slug: string;
    };
    cluster: {
      id: string;
    };
    region: {
      id: string;
      name: string;
    };
    build: {
      id: string;
    };
  };
  // Key-value storage API
  kv: {
    // KV methods (see documentation for details)
  };
}