Endpoints

import imgEndpointEnvVars from "./endpoints/endpoint-env-vars.png";

Local Development

No configuration is needed for local development. RivetKit runs entirely on your local machine without any extra configuration to run Rivet Actors.

Production Deployment

When deploying to production, you need to configure endpoints so your backend can communicate with Rivet Engine and clients can reach your actors.

Private Endpoint

The private endpoint tells your backend where to find the Rivet Engine.

RIVET_ENDPOINT=https://my-namespace:[email protected]

import { actor, setup } from "rivetkit";

const myActor = actor({
  state: {},
  actions: {}
});

const registry = setup({
  use: { myActor },
  endpoint: "https://my-namespace:[email protected]",
});

Public Endpoint

The public endpoint tells clients where to connect to reach your actors.

This endpoint and token will be exposed to the internet. Use a public token (pk_), not your secret token (sk_).

The public endpoint is only required if using the serverless runtime mode and if you have a frontend using RivetKit.

RIVET_PUBLIC_ENDPOINT=https://my-namespace:[email protected]

import { actor, setup } from "rivetkit";

const myActor = actor({
  state: {},
  actions: {}
});

const registry = setup({
  use: { myActor },
  serverless: {
    publicEndpoint: "https://my-namespace:[email protected]",
  },
});

Advanced

URL Auth Syntax

Endpoint URLs support embedding namespace and token directly in the URL:

https://namespace:token@host/path

This is the recommended approach for simplicity. Alternatively, you can use separate environment variables:

RIVET_ENDPOINT=https://api.rivet.dev
RIVET_NAMESPACE=my-namespace
RIVET_TOKEN=sk_xxxxx

Security

In serverless mode, the private endpoint is used to validate that requests to GET /api/rivet/start are coming from your trusted Rivet endpoint. If the private endpoint is not configured, anyone can run a self-hosted instance of Rivet and connect to your backend from any endpoint.

How Clients Connect

This flow applies to serverless runtime mode. For runner runtime mode or clients configured to connect directly to Rivet, clients connect directly to Rivet and this metadata flow is not needed.

When a client connects to your serverless application, it follows this flow:

1. Client makes a request to https://my-app.example.com/api/rivet/metadata
2. Your app returns the public endpoint configuration:
   jsonCopy

   {
     "clientEndpoint": "https://api.rivet.dev",
     "clientNamespace": "my-namespace",
     "clientToken": "pk_xxxxx"
   }
   

3. Client caches these values and uses them for subsequent requests
4. Client connects to https://api.rivet.dev/gateway/{actor}, which routes requests to your actors

This indirection exists because Rivet acts as a gateway between clients and your actors. This is because Rivet handles routing, load balancing, and actor lifecycle management of actors.

Reference