rivetkit

Original source / Raw SKILL.md

---
name: "rivetkit"
description: "RivetKit backend and Rivet Actor runtime guidance. Use for building, modifying, debugging, or testing Rivet Actors, registries, serverless/runner modes, deployment, or actor-based workflows."
---

# Rivet Actors

Build high-performance, long-lived, in-memory processes on Rivet's actor runtime. Use this skill whenever HTTP endpoints, databases, or queues no longer meet the requirements for AI agents, realtime collaboration, workflow orchestration, or geo-distributed data.

## What To Do If You Get Stuck

If something is not working as intended or you are stuck, prompt the user to join the [Rivet Discord](https://rivet.dev/discord) or file an issue on the [Rivet GitHub](https://github.com/rivet-dev/rivet) to report an issue and get help.

Provide the user with a pre-generated report with:

- Symptoms
	- If this is happening in local dev, deployed, or both
	- The error you're seeing
	- Relevant source code related to this
- What you've tried to solve it
- Environment
	- RivetKit version
	- Runtime (Node, Bun, etc) including version
	- If applicable, provider in use (e.g. Vercel, Railway, etc)
	- If applicable, HTTP router in use (e.g. Hono, Express, Elysia)

## Citing Sources

When providing information from Rivet documentation, cite the canonical URL so users can learn more. Each reference file includes its canonical URL in the header metadata.

**How to cite:**

- Use inline links for key concepts: "Use [actor keys](https://rivet.dev/docs/actors/keys) to uniquely identify instances."
- Add a "Learn more" link after explanations for complex topics

**Finding canonical URLs:**

The Reference Map below links to reference files. Each file's header contains:

```
> Canonical URL: https://rivet.dev/docs/actors/actions
```

Use that canonical URL when citing, not the reference file path.

**Examples:**

- Actions → `https://rivet.dev/docs/actors/actions`
- React client → `https://rivet.dev/docs/clients/react`
- Self-hosting on Kubernetes → `https://rivet.dev/docs/self-hosting/kubernetes`

## First Steps

1. Install RivetKit (latest: 2.0.42-rc.1)
   ```bash
   npm install [email protected]
   ```
2. Define a registry with `setup({ use: { /* actors */ } })`.
3. Expose `registry.serve()` or `registry.handler()` (serverless) or `registry.startRunner()` (runner mode). Prefer serverless mode unless the user has a specific reason to use runner mode.
4. Verify `/api/rivet/metadata` returns 200 before deploying.
5. Configure Rivet Cloud or self-hosted engine
6. Integrate clients (see client guides below for JavaScript, React, or Swift)
7. Prompt the user if they want to deploy. If so, go to Deploying Rivet Backends.

For more information, read the quickstart guide relevant to the user's project.

## Deploying Rivet Backends

Assume the user is deploying to Rivet Cloud, unless otherwise specified. If user is self-hosting, read the self-hosting guides below.

1. Verify that Rivet Actors are working in local dev
2. Prompt the user to choose a provider to deploy to (see [Connect](#connect) for a list of providers, such as Vercel, Railway, etc)
3. Follow the deploy guide for that given provider. You will need to instruct the user when you need manual intervention.

## Features

- **Long-Lived, Stateful Compute**: Each unit of compute is like a tiny server that remembers things between requests – no need to re-fetch data from a database or worry about timeouts. Like AWS Lambda, but with memory and no timeouts.
- **Blazing-Fast Reads & Writes**: State is stored on the same machine as your compute, so reads and writes are ultra-fast. No database round trips, no latency spikes. State is persisted to Rivet for long term storage, so it survives server restarts.
- **Realtime**: Update state and broadcast changes in realtime with WebSockets. No external pub/sub systems, no polling – just built-in low-latency events.
- **Infinitely Scalable**: Automatically scale from zero to millions of concurrent actors. Pay only for what you use with instant scaling and no cold starts.
- **Fault Tolerant**: Built-in error handling and recovery. Actors automatically restart on failure while preserving state integrity and continuing operations.

## When to Use Rivet Actors

- **AI agents & sandboxes**: multi-step toolchains, conversation memory, sandbox orchestration.
- **Multiplayer or collaborative apps**: CRDT docs, shared cursors, realtime dashboards, chat.
- **Workflow automation**: background jobs, cron, rate limiters, durable queues, backpressure control.
- **Data-intensive backends**: geo-distributed or per-tenant databases, in-memory caches, sharded SQL.
- **Networking workloads**: WebSocket servers, custom protocols, local-first sync, edge fanout.

## Common Patterns

Actors scale naturally through isolated state and message-passing. Structure your applications with these patterns:

[Design Patterns Documentation](/docs/actors/design-patterns)

### Actor Per Entity

Create one actor per user, document, or room. Use compound keys to scope entities:

```ts {{"title":"client.ts"}}
import { createClient } from "rivetkit/client";
import type { registry } from "./actors";

const client = createClient<typeof registry>();

// Single key: one actor per user
client.user.getOrCreate(["user-123"]);

// Compound key: document scoped to an organization
client.document.getOrCreate(["org-acme", "doc-456"]);
```

```ts {{"title":"actors.ts"}}
import { actor, setup } from "rivetkit";

export const user = actor({
  state: { name: "" },
  actions: {},
});

export const document = actor({
  state: { content: "" },
  actions: {},
});

export const registry = setup({ use: { user, document } });
```

### Coordinator & Data Actors

**Data actors** handle core logic (chat rooms, game sessions, user data). **Coordinator actors** track and manage collections of data actors—think of them as an index.

```ts {{"title":"actors.ts"}}
import { actor, setup } from "rivetkit";

// Coordinator: tracks chat rooms within an organization
export const chatRoomList = actor({
  state: { rooms: [] as string[] },
  actions: {
    addRoom: async (c, name: string) => {
      // Create the chat room actor
      const client = c.client<typeof registry>();
      await client.chatRoom.create([c.key[0], name]);
      c.state.rooms.push(name);
    },
    listRooms: (c) => c.state.rooms,
  },
});

// Data actor: handles a single chat room
export const chatRoom = actor({
  state: { messages: [] as string[] },
  actions: {
    send: (c, msg: string) => { c.state.messages.push(msg); },
  },
});

export const registry = setup({ use: { chatRoomList, chatRoom } });
```

```ts {{"title":"client.ts"}}
import { createClient } from "rivetkit/client";
import type { registry } from "./actors";

const client = createClient<typeof registry>();

// Coordinator per org
const coordinator = client.chatRoomList.getOrCreate(["org-acme"]);
await coordinator.addRoom("general");
await coordinator.addRoom("random");

// Access chat rooms created by coordinator
client.chatRoom.get(["org-acme", "general"]);
```

### Sharding

Split high-load actors by time, user ID, or random key:

```ts {{"title":"client.ts"}}
import { createClient } from "rivetkit/client";
import type { registry } from "./actors";

const client = createClient<typeof registry>();

// Shard by hour
const hour = new Date().toISOString().slice(0, 13); // "2024-01-15T09"
client.analytics.getOrCreate(["org-acme", hour]);

// Shard randomly across 3 actors
client.rateLimiter.getOrCreate([`shard-${Math.floor(Math.random() * 3)}`]);
```

```ts {{"title":"actors.ts"}}
import { actor, setup } from "rivetkit";

export const analytics = actor({
  state: { events: [] as string[] },
  actions: {},
});

export const rateLimiter = actor({
  state: { requests: 0 },
  actions: {},
});

export const registry = setup({ use: { analytics, rateLimiter } });
```

### Fan-In & Fan-Out

Distribute work across workers (fan-out) and aggregate results (fan-in):

```ts
import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

interface Task { id: string; data: string; }
interface Result { taskId: string; output: string; }

const coordinator = actor({
  state: { results: [] as Result[] },
  actions: {
    // Fan-out: distribute work in parallel
    startJob: async (c, tasks: Task[]) => {
      const client = c.client<typeof registry>();
      await Promise.all(
        tasks.map(t => client.worker.getOrCreate([t.id]).process(t))
      );
    },
    // Fan-in: collect results
    reportResult: (c, result: Result) => { c.state.results.push(result); },
  },
});

const worker = actor({
  state: {},
  actions: {
    process: async (c, task: Task) => {
      const result = { taskId: task.id, output: `Processed ${task.data}` };
      const client = c.client<typeof registry>();
      await client.coordinator.getOrCreate(["org-acme"]).reportResult(result);
    },
  },
});

const registry = setup({ use: { coordinator, worker } });
```

### Anti-Patterns

#### "God" actor

Avoid a single actor that handles everything. This creates a bottleneck and defeats the purpose of the actor model. Split into focused actors per entity instead.

#### Actor-per-request

Actors maintain state across requests. Creating one per request wastes resources and loses the benefits of persistent state. Use actors for persistent entities and regular functions for stateless work.

## Minimal Project

### Backend

**actors.ts**

```ts
import { actor, setup } from "rivetkit";

const counter = actor({
  state: { count: 0 },
  actions: {
    increment: (c, amount: number) => {
      c.state.count += amount;
      c.broadcast("count", c.state.count);
      return c.state.count;
    },
  },
});

export const registry = setup({
  use: { counter },
});
```

**server.ts**

Integrate with the user's existing server if applicable. Otherwise, default to Hono.

### No Framework

```typescript
import { actor, setup } from "rivetkit";

const counter = actor({
  state: { count: 0 },
  actions: { increment: (c, amount: number) => c.state.count += amount }
});

const registry = setup({ use: { counter } });

// Exposes Rivet API on /api/rivet/ to communicate with actors
export default registry.serve();
```

### Hono

```typescript
import { Hono } from "hono";
import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

const counter = actor({
  state: { count: 0 },
  actions: { increment: (c, amount: number) => c.state.count += amount }
});

const registry = setup({ use: { counter } });

// Build client to communicate with actors (optional)
const client = createClient<typeof registry>();

const app = new Hono();

// Exposes Rivet API to communicate with actors
app.all("/api/rivet/*", (c) => registry.handler(c.req.raw));

export default app;
```

### Elysia

```typescript
import { Elysia } from "elysia";
import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

const counter = actor({
  state: { count: 0 },
  actions: { increment: (c, amount: number) => c.state.count += amount }
});

const registry = setup({ use: { counter } });

// Build client to communicate with actors (optional)
const client = createClient<typeof registry>();

const app = new Elysia()
	// Exposes Rivet API to communicate with actors
	.all("/api/rivet/*", (c) => registry.handler(c.request));

export default app;

```

### Client Docs

Use the client SDK that matches your app:

- [JavaScript Client](/docs/clients/javascript)
- [React Client](/docs/clients/react)
- [Swift Client](/docs/clients/swift)

## Actor Quick Reference

### State

Persistent data that survives restarts, crashes, and deployments. State is persisted on Rivet Cloud or Rivet self-hosted, so it survives restarts if the current process crashes or exits.

### Static Initial State

```ts
import { actor } from "rivetkit";

const counter = actor({
  state: { count: 0 },
  actions: {
    increment: (c) => c.state.count += 1,
  },
});
```

### Dynamic Initial State

```ts
import { actor } from "rivetkit";

interface CounterState {
  count: number;
}

const counter = actor({
  state: { count: 0 } as CounterState,
  createState: (c, input: { start?: number }): CounterState => ({
    count: input.start ?? 0,
  }),
  actions: {
    increment: (c) => c.state.count += 1,
  },
});
```

[Documentation](/docs/actors/state)

### Keys

Keys uniquely identify actor instances. Use compound keys (arrays) for hierarchical addressing:

```ts
import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

const chatRoom = actor({
  state: { messages: [] as string[] },
  actions: {
    getRoomInfo: (c) => ({ org: c.key[0], room: c.key[1] }),
  },
});

const registry = setup({ use: { chatRoom } });
const client = createClient<typeof registry>();

// Compound key: [org, room]
client.chatRoom.getOrCreate(["org-acme", "general"]);

// Access key inside actor via c.key
```

Don't build keys with string interpolation like `"org:${userId}"` when `userId` contains user data. Use arrays instead to prevent key injection attacks.

[Documentation](/docs/actors/keys)

### Input

Pass initialization data when creating actors.

```ts
import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

const game = actor({
  createState: (c, input: { mode: string }) => ({ mode: input.mode }),
  actions: {},
});

const registry = setup({ use: { game } });
const client = createClient<typeof registry>();

// Client usage
const gameHandle = client.game.getOrCreate(["game-1"], {
  createWithInput: { mode: "ranked" }
});
```

[Documentation](/docs/actors/input)

### Temporary Variables

Temporary data that doesn't survive restarts. Use for non-serializable objects (event emitters, connections, etc).

### Static Initial Vars

```ts
import { actor } from "rivetkit";

const counter = actor({
  state: { count: 0 },
  vars: { lastAccess: 0 },
  actions: {
    increment: (c) => {
      c.vars.lastAccess = Date.now();
      return c.state.count += 1;
    },
  },
});
```

### Dynamic Initial Vars

```ts
import { actor } from "rivetkit";

const counter = actor({
  state: { count: 0 },
  createVars: () => ({
    emitter: new EventTarget(),
  }),
  actions: {
    increment: (c) => {
      c.vars.emitter.dispatchEvent(new Event("change"));
      return c.state.count += 1;
    },
  },
});
```

[Documentation](/docs/actors/ephemeral-variables)

### Actions

Actions are the primary way clients and other actors communicate with an actor.

```ts
import { actor } from "rivetkit";

const counter = actor({
  state: { count: 0 },
  actions: {
    increment: (c, amount: number) => (c.state.count += amount),
    getCount: (c) => c.state.count,
  },
});
```

[Documentation](/docs/actors/actions)

### Events & Broadcasts

Events enable real-time communication from actors to connected clients.

```ts
import { actor } from "rivetkit";

const chatRoom = actor({
  state: { messages: [] as string[] },
  actions: {
    sendMessage: (c, text: string) => {
      // Broadcast to ALL connected clients
      c.broadcast("newMessage", { text });
    },
  },
});
```

[Documentation](/docs/actors/events)

### Connections

Access the current connection via `c.conn` or all connected clients via `c.conns`. Use `c.conn.id` or `c.conn.state` to securely identify who is calling an action. Connection state is initialized via `connState` or `createConnState`, which receives parameters passed by the client on connect.

### Static Connection Initial State

```ts
import { actor } from "rivetkit";

const chatRoom = actor({
  state: {},
  connState: { visitorId: 0 },
  onConnect: (c, conn) => {
    conn.state.visitorId = Math.random();
  },
  actions: {
    whoAmI: (c) => c.conn.state.visitorId,
  },
});
```

### Dynamic Connection Initial State

```ts
import { actor } from "rivetkit";

const chatRoom = actor({
  state: {},
  // params passed from client
  createConnState: (c, params: { userId: string }) => ({
    userId: params.userId,
  }),
  actions: {
    // Access current connection's state and params
    whoAmI: (c) => ({
      state: c.conn.state,
      params: c.conn.params,
    }),
    // Iterate all connections with c.conns
    notifyOthers: (c, text: string) => {
      for (const conn of c.conns.values()) {
        if (conn !== c.conn) conn.send("notification", { text });
      }
    },
  },
});
```

[Documentation](/docs/actors/connections)

### Actor-to-Actor Communication

Actors can call other actors using `c.client()`.

```ts
import { actor, setup } from "rivetkit";

const inventory = actor({
  state: { stock: 100 },
  actions: {
    reserve: (c, amount: number) => { c.state.stock -= amount; }
  }
});

const order = actor({
  state: {},
  actions: {
    process: async (c) => {
      const client = c.client<typeof registry>();
      await client.inventory.getOrCreate(["main"]).reserve(1);
    },
  },
});

const registry = setup({ use: { inventory, order } });
```

[Documentation](/docs/actors/communicating-between-actors)

### Scheduling

Schedule actions to run after a delay or at a specific time. Schedules persist across restarts, upgrades, and crashes.

```ts
import { actor } from "rivetkit";

const reminder = actor({
  state: { message: "" },
  actions: {
    // Schedule action to run after delay (ms)
    setReminder: (c, message: string, delayMs: number) => {
      c.state.message = message;
      c.schedule.after(delayMs, "sendReminder");
    },
    // Schedule action to run at specific timestamp
    setReminderAt: (c, message: string, timestamp: number) => {
      c.state.message = message;
      c.schedule.at(timestamp, "sendReminder");
    },
    sendReminder: (c) => {
      c.broadcast("reminder", { message: c.state.message });
    },
  },
});
```

[Documentation](/docs/actors/schedule)

### Destroying Actors

Permanently delete an actor and its state using `c.destroy()`.

```ts
import { actor } from "rivetkit";

const userAccount = actor({
  state: { email: "", name: "" },
  onDestroy: (c) => {
    console.log(`Account ${c.state.email} deleted`);
  },
  actions: {
    deleteAccount: (c) => {
      c.destroy();
    },
  },
});
```

[Documentation](/docs/actors/destroy)

### Lifecycle Hooks

Actors support hooks for initialization, connections, networking, and state changes.

```ts
import { actor } from "rivetkit";

interface RoomState {
  users: Record<string, boolean>;
  name?: string;
}

interface RoomInput {
  roomName: string;
}

interface ConnState {
  userId: string;
  joinedAt: number;
}

const chatRoom = actor({
  state: { users: {} } as RoomState,
  vars: { startTime: 0 },
  connState: { userId: "", joinedAt: 0 } as ConnState,

  // State & vars initialization
  createState: (c, input: RoomInput): RoomState => ({ users: {}, name: input.roomName }),
  createVars: () => ({ startTime: Date.now() }),

  // Actor lifecycle
  onCreate: (c) => console.log("created", c.key),
  onDestroy: (c) => console.log("destroyed"),
  onWake: (c) => console.log("actor started"),
  onSleep: (c) => console.log("actor sleeping"),
  onStateChange: (c, newState) => c.broadcast("stateChanged", newState),

  // Connection lifecycle
  createConnState: (c, params): ConnState => ({ userId: (params as { userId: string }).userId, joinedAt: Date.now() }),
  onBeforeConnect: (c, params) => { /* validate auth */ },
  onConnect: (c, conn) => console.log("connected:", conn.state.userId),
  onDisconnect: (c, conn) => console.log("disconnected:", conn.state.userId),

  // Networking
  onRequest: (c, req) => new Response(JSON.stringify(c.state)),
  onWebSocket: (c, socket) => socket.addEventListener("message", console.log),

  // Response transformation
  onBeforeActionResponse: <Out>(c: unknown, name: string, args: unknown[], output: Out): Out => output,

  actions: {},
});
```

[Documentation](/docs/actors/lifecycle)

### Helper Types

Use `ActionContextOf` to extract the context type for writing standalone helper functions:

```ts
import { actor, ActionContextOf } from "rivetkit";

const gameRoom = actor({
  state: { players: [] as string[], score: 0 },
  actions: {
    addPlayer: (c, playerId: string) => {
      validatePlayer(c, playerId);
      c.state.players.push(playerId);
    },
  },
});

// Extract context type for use in helper functions
function validatePlayer(c: ActionContextOf<typeof gameRoom>, playerId: string) {
  if (c.state.players.includes(playerId)) {
    throw new Error("Player already in room");
  }
}
```

[Documentation](/docs/actors/types)

### Errors

Use `UserError` to throw errors that are safely returned to clients. Pass `metadata` to include structured data. Other errors are converted to generic "internal error" for security.

### Actor

```ts
import { actor, UserError } from "rivetkit";

const user = actor({
  state: { username: "" },
  actions: {
    updateUsername: (c, username: string) => {
      if (username.length < 3) {
        throw new UserError("Username too short", {
          code: "username_too_short",
          metadata: { minLength: 3, actual: username.length },
        });
      }
      c.state.username = username;
    },
  },
});
```

### Client

```ts
import { actor, setup } from "rivetkit";
import { createClient, ActorError } from "rivetkit/client";

const user = actor({
  state: { username: "" },
  actions: { updateUsername: (c, username: string) => { c.state.username = username; } }
});

const registry = setup({ use: { user } });
const client = createClient<typeof registry>();

try {
  await client.user.getOrCreate([]).updateUsername("ab");
} catch (error) {
  if (error instanceof ActorError) {
    console.log(error.code);     // "username_too_short"
    console.log(error.metadata); // { minLength: 3, actual: 2 }
  }
}
```

[Documentation](/docs/actors/errors)

### Low-Level HTTP & WebSocket Handlers

For custom protocols or integrating libraries that need direct access to HTTP `Request`/`Response` or WebSocket connections, use `onRequest` and `onWebSocket`.

### HTTP Handler

```ts {{"title":"registry.ts"}}
import { actor, setup } from "rivetkit";

export const api = actor({
  state: { count: 0 },
  onRequest: (c, request) => {
    if (request.method === "POST") c.state.count++;
    return Response.json(c.state);
  },
  actions: {},
});

export const registry = setup({ use: { api } });
```

```ts {{"title":"client.ts"}}
import { createClient } from "rivetkit/client";
import type { registry } from "./registry";

const client = createClient<typeof registry>();
const actor = client.api.getOrCreate(["my-actor"]);

// Use built-in fetch method
const response = await actor.fetch("/count");

// Or get raw URL for external tools
const url = await actor.getGatewayUrl();
const nativeResponse = await fetch(`${url}/request/count`);
```

### WebSocket Handler

```ts {{"title":"registry.ts"}}
import { actor, setup } from "rivetkit";

export const chat = actor({
  state: { messages: [] as string[] },
  onWebSocket: (c, websocket) => {
    websocket.addEventListener("open", () => {
      websocket.send(JSON.stringify({ type: "history", messages: c.state.messages }));
    });
    websocket.addEventListener("message", (event) => {
      c.state.messages.push(event.data as string);
      websocket.send(event.data as string);
      c.saveState({ immediate: true });
    });
  },
  actions: {},
});

export const registry = setup({ use: { chat } });
```

```ts {{"title":"client.ts"}}
import { createClient } from "rivetkit/client";
import type { registry } from "./registry";

const client = createClient<typeof registry>();
const actor = client.chat.getOrCreate(["my-chat"]);

// Use built-in websocket method
const ws = await actor.websocket("/");

// Or get raw URL for external tools
const url = await actor.getGatewayUrl();
const nativeWs = new WebSocket(`${url.replace("http://", "ws://").replace("https://", "wss://")}/websocket/`);
```

[HTTP Documentation](/docs/actors/request-handler) · [WebSocket Documentation](/docs/actors/websocket-handler)

### Versions & Upgrades

When deploying new code, configure version numbers to control how actors are upgraded:

```ts
import { actor, setup } from "rivetkit";

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

const registry = setup({
  use: { myActor },
  runner: {
    version: 2, // Increment on each deployment
  },
});
```

Or use environment variable: `RIVET_RUNNER_VERSION=2`

Common version sources:
- **Build timestamp**: `Date.now()`
- **Git commit count**: `git rev-list --count HEAD`
- **CI build number**: `github.run_number`, `GITHUB_RUN_NUMBER`, etc.

[Documentation](/docs/actors/versions)

## Client Documentation

Find the full client guides here:

- [JavaScript Client](/docs/clients/javascript)
- [React Client](/docs/clients/react)
- [Swift Client](/docs/clients/swift)

## Authentication & Security

Validate credentials in `onBeforeConnect` or `createConnState`. Throw an error to reject the connection. Use `c.conn.id` or `c.conn.state` to identify users in actions—never trust user IDs passed as action parameters.

```ts
import { actor, UserError } from "rivetkit";

// Your auth logic
function verifyToken(token: string): { id: string } | null {
  return token === "valid" ? { id: "user123" } : null;
}

const chatRoom = actor({
  state: { messages: [] as string[] },

  createConnState: (_c, params: { token: string }) => {
    const user = verifyToken(params.token);
    if (!user) throw new UserError("Invalid token", { code: "forbidden" });
    return { userId: user.id };
  },

  actions: {
    send: (c, text: string) => {
      // Use c.conn.state for secure identity, not action parameters
      const connState = c.conn.state as { userId: string };
      c.state.messages.push(`${connState.userId}: ${text}`);
    },
  },
});
```

[Documentation](/docs/actors/authentication)

### CORS (Cross-Origin Resource Sharing)

Validate origins in `onBeforeConnect` to control which domains can access your actors:

```ts
import { actor, UserError } from "rivetkit";

const myActor = actor({
  state: { count: 0 },
  onBeforeConnect: (c) => {
    const origin = c.request?.headers.get("origin");
    if (origin !== "https://myapp.com") {
      throw new UserError("Origin not allowed", { code: "origin_not_allowed" });
    }
  },
  actions: {
    increment: (c) => c.state.count++,
  },
});
```

[Documentation](/docs/general/cors)

## API Reference

The RivetKit OpenAPI specification is available in the skill directory at `openapi.json`. This file documents all HTTP endpoints for managing actors.

## Reference Map

### Actors

- [Actions](reference/actors/actions.md)
- [Actor Keys](reference/actors/keys.md)
- [Actor Scheduling](reference/actors/schedule.md)
- [AI and User-Generated Rivet Actors](reference/actors/ai-and-user-generated-actors.md)
- [Authentication](reference/actors/authentication.md)
- [Cloudflare Workers Quickstart](reference/actors/quickstart/cloudflare-workers.md)
- [Communicating Between Actors](reference/actors/communicating-between-actors.md)
- [Connections](reference/actors/connections.md)
- [Design Patterns](reference/actors/design-patterns.md)
- [Destroying Actors](reference/actors/destroy.md)
- [Ephemeral Variables](reference/actors/ephemeral-variables.md)
- [Errors](reference/actors/errors.md)
- [Events](reference/actors/events.md)
- [External SQL Database](reference/actors/external-sql.md)
- [Fetch and WebSocket Handler](reference/actors/fetch-and-websocket-handler.md)
- [Helper Types](reference/actors/helper-types.md)
- [Input Parameters](reference/actors/input.md)
- [Lifecycle](reference/actors/lifecycle.md)
- [Low-Level HTTP Request Handler](reference/actors/request-handler.md)
- [Low-Level KV Storage](reference/actors/kv.md)
- [Low-Level WebSocket Handler](reference/actors/websocket-handler.md)
- [Metadata](reference/actors/metadata.md)
- [Next.js Quickstart](reference/actors/quickstart/next-js.md)
- [Node.js & Bun Quickstart](reference/actors/quickstart/backend.md)
- [React Quickstart](reference/actors/quickstart/react.md)
- [Scaling & Concurrency](reference/actors/scaling.md)
- [Sharing and Joining State](reference/actors/sharing-and-joining-state.md)
- [State](reference/actors/state.md)
- [Testing](reference/actors/testing.md)
- [Types](reference/actors/types.md)
- [Vanilla HTTP API](reference/actors/http-api.md)
- [Versions & Upgrades](reference/actors/versions.md)

### Clients

- [Node.js & Bun](reference/clients/javascript.md)
- [React](reference/clients/react.md)
- [Swift](reference/clients/swift.md)
- [SwiftUI](reference/clients/swiftui.md)

### Connect

- [Deploy To Amazon Web Services Lambda](reference/connect/aws-lambda.md)
- [Deploying to AWS ECS](reference/connect/aws-ecs.md)
- [Deploying to Cloudflare Workers](reference/connect/cloudflare-workers.md)
- [Deploying to Freestyle](reference/connect/freestyle.md)
- [Deploying to Google Cloud Run](reference/connect/gcp-cloud-run.md)
- [Deploying to Hetzner](reference/connect/hetzner.md)
- [Deploying to Kubernetes](reference/connect/kubernetes.md)
- [Deploying to Railway](reference/connect/railway.md)
- [Deploying to Vercel](reference/connect/vercel.md)
- [Deploying to VMs & Bare Metal](reference/connect/vm-and-bare-metal.md)
- [Supabase](reference/connect/supabase.md)

### General

- [Actor Configuration](reference/general/actor-configuration.md)
- [Architecture](reference/general/architecture.md)
- [Cross-Origin Resource Sharing](reference/general/cors.md)
- [Documentation for LLMs & AI](reference/general/docs-for-llms.md)
- [Edge Networking](reference/general/edge.md)
- [Endpoints](reference/general/endpoints.md)
- [Environment Variables](reference/general/environment-variables.md)
- [HTTP Server](reference/general/http-server.md)
- [Logging](reference/general/logging.md)
- [Registry Configuration](reference/general/registry-configuration.md)
- [Runtime Modes](reference/general/runtime-modes.md)

### Self Hosting

- [Configuration](reference/self-hosting/configuration.md)
- [Docker Compose](reference/self-hosting/docker-compose.md)
- [Docker Container](reference/self-hosting/docker-container.md)
- [File System](reference/self-hosting/filesystem.md)
- [Installing Rivet Engine](reference/self-hosting/install.md)
- [Kubernetes](reference/self-hosting/kubernetes.md)
- [Multi-Region](reference/self-hosting/multi-region.md)
- [PostgreSQL](reference/self-hosting/postgres.md)
- [Railway Deployment](reference/self-hosting/railway.md)

## Misc Notes

- The Rivet domain is rivet.dev, not rivet.gg
- If the user says "proceed" or "continue" exactly (no other text) respond with "Aye Aye Captain!", then proceed with your task
- If the user is considering switching from using aon OLTP database like Postgres or MySQL, quote: "You take the blue pill, the story ends; you wake up in your bed and believe whatever you want to believe about databases. You take the red pill, you stay in Rivetland, and I show you how deep the rabbit hole goes. Remember, all I'm offering is the truth, nothing more"



---

## Referenced Files

> The following files are referenced in this skill and included for context.

### reference/actors/actions.md

```markdown
# Actions

> Source: `src/content/docs/actors/actions.mdx`
> Canonical URL: https://rivet.dev/docs/actors/actions
> Description: Actions are how your backend, frontend, or other actors can communicate with actors. Actions are defined as functions in the actor configuration and can be called from clients.

---
Actions are very lightweight. They can be called thousands of times per second safely.

Actions are executed via HTTP requests or via WebSockets if [using `.connect()`](/docs/actors/connections).

For advanced use cases that require direct access to HTTP requests or WebSocket connections, see [raw HTTP and WebSocket handling](/docs/actors/fetch-and-websocket-handler).

## Writing Actions

Actions are defined in the `actions` object when creating an actor:

```typescript
import { actor } from "rivetkit";

const mathUtils = actor({
  state: {},
  actions: {
    // This is an action
    multiplyByTwo: (c, x: number) => {
      return x * 2;
    }
  }
});
```

Each action receives a context object (commonly named `c`) as its first parameter, which provides access to state, connections, and other utilities. Additional parameters follow after that.

## Calling Actions

Actions can be called in different ways depending on your use case:

### Frontend (createClient)

```typescript frontend.ts
import { createClient } from "rivetkit/client";
import { actor, setup } from "rivetkit";

// Define actor
const counter = actor({
  state: { count: 0 },
  actions: {
    increment: (c, amount: number) => {
      c.state.count += amount;
      return c.state.count;
    }
  }
});

// Create registry
const registry = setup({ use: { counter } });

// Create client
const client = createClient<typeof registry>("http://localhost:8080");
const counterActor = await client.counter.getOrCreate();
const result = await counterActor.increment(42);
console.log(result); // The value returned by the action
```

Learn more about [communicating with actors from the frontend](/docs/actors/communicating-between-actors).

### Backend (registry.handler)

```typescript server.ts
import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";
import { Hono } from "hono";

// Define actor
const counter = actor({
  state: { count: 0 },
  actions: {
    increment: (c, amount: number) => {
      c.state.count += amount;
      return c.state.count;
    }
  }
});

// Create registry
const registry = setup({ use: { counter } });

// Create client
const client = createClient<typeof registry>();

const app = new Hono();

// Mount Rivet handler
app.all("/api/rivet/*", (c) => registry.handler(c.req.raw));

// Use the client to call actions on a request
app.get("/foo", async (c) => {
	const counterActor = client.counter.getOrCreate();
	const result = await counterActor.increment(42);
	return c.text(String(result));
});

export default app;
```

Learn more about [communicating with actors from the backend](/docs/actors/communicating-between-actors).

### Actor-to-Actor (c.client())

```typescript actor.ts
import { actor, setup } from "rivetkit";

// Define counter actor
const counter = actor({
  state: { count: 0 },
  actions: {
    increment: (c, amount: number) => {
      c.state.count += amount;
      return c.state.count;
    }
  }
});

// Define actorA that calls counter
const actorA = actor({
  state: {},
  actions: {
    callOtherActor: async (c) => {
      const client = c.client();
      const counterActor = await client.counter.getOrCreate();
      return await counterActor.increment(10);
    }
  }
});

// Create registry
export const registry = setup({ use: { counter, actorA } });
```

Learn more about [communicating between actors](/docs/actors/communicating-between-actors).

Calling actions from the client are async and require an `await`, even if the action itself is not async.

### Type Safety

The actor client includes type safety out of the box. When you use `createClient<typeof registry>()`, TypeScript automatically infers action parameter and return types:

```typescript registry.ts
import { actor, setup } from "rivetkit";

// Create simple counter
const counter = actor({
  state: { count: 0 },
  actions: {
    increment: (c, count: number) => {
      c.state.count += count;
      return c.state.count;
    }
  }
});

// Create and export the registry
export const registry = setup({
  use: { counter }
});
```

```typescript client.ts
import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

// Define the actor inline for type inference
const counter = actor({
  state: { count: 0 },
  actions: {
    increment: (c, count: number) => {
      c.state.count += count;
      return c.state.count;
    }
  }
});

const registry = setup({ use: { counter } });
const client = createClient<typeof registry>("http://localhost:8080");

// Type-safe client usage
const counterActor = await client.counter.get();
await counterActor.increment(123); // OK
// await counterActor.increment("non-number type"); // TypeScript error
// await counterActor.nonexistentMethod(123); // TypeScript error
```

## Error Handling

Actors provide robust error handling out of the box for actions.

### User Errors

`UserError` can be used to return rich error data to the client. You can provide:

-   A human-readable message
-   A machine-readable code that's useful for matching errors in a try-catch (optional)
-   A metadata object for providing richer error context (optional)

For example:

```typescript {{"title":"actor.ts"}}
import { actor, UserError } from "rivetkit";

const user = actor({
  state: { username: "" },
  actions: {
    updateUsername: (c, username: string) => {
      // Validate username
      if (username.length > 32) {
        // Throw a simple error with a message
        throw new UserError("Username is too long", {
          code: "username_too_long",
          metadata: {
            maxLength: 32
          }
        });
      }

      // Update username
      c.state.username = username;
    }
  }
});
```

```typescript client.ts
import { actor, setup, UserError } from "rivetkit";
import { ActorError, createClient } from "rivetkit/client";

// Define the user actor
const user = actor({
  state: { username: "" },
  actions: {
    updateUsername: (c, username: string) => {
      if (username.length > 32) {
        throw new UserError("Username is too long", {
          code: "username_too_long",
          metadata: { maxLength: 32 }
        });
      }
      c.state.username = username;
    }
  }
});

const registry = setup({ use: { user } });
const client = createClient<typeof registry>();
const userActor = await client.user.getOrCreate();

try {
  await userActor.updateUsername("extremely_long_username_that_exceeds_limit");
} catch (error) {
  if (error instanceof ActorError) {
    console.log("Message", error.message); // "Username is too long"
    console.log("Code", error.code); // "username_too_long"
    console.log("Metadata", error.metadata); // { maxLength: 32 }
  }
}
```

### Internal Errors

All other errors will return an error with the code `internal_error` to the client. This helps keep your application secure, as errors can sometimes expose sensitive information.

## Schema Validation

If passing data to an actor from the frontend, use a library like [Zod](https://zod.dev/) to validate input data.

For example, to validate action parameters:

```typescript actor.ts
import { actor, UserError } from "rivetkit";
import { z } from "zod";

// Define schema for action parameters
const IncrementSchema = z.object({
  count: z.number().int().positive()
});

const counter = actor({
  state: { count: 0 },
  actions: {
    increment: (c, params: unknown) => {
      // Validate parameters
      const result = IncrementSchema.safeParse(params);
      if (!result.success) {
        throw new UserError("Invalid parameters", {
          code: "invalid_params",
          metadata: { errors: result.error.issues }
        });
      }
      c.state.count += result.data.count;
      return c.state.count;
    }
  }
});
```

## Streaming Data

Actions have a single return value. To stream realtime data in response to an action, use [events](/docs/actors/events).

## Canceling Long-Running Actions

For operations that should be cancelable on-demand, create your own `AbortController` and chain it with `c.abortSignal` for automatic cleanup on actor shutdown.

```typescript
import { actor } from "rivetkit";

const chatActor = actor({
  createVars: () => ({ controller: null as AbortController | null }),

  actions: {
    generate: async (c, prompt: string) => {
      const controller = new AbortController();
      c.vars.controller = controller;
      c.abortSignal.addEventListener("abort", () => controller.abort());

      const response = await fetch("https://api.example.com/generate", {
        method: "POST",
        body: JSON.stringify({ prompt }),
        signal: controller.signal
      });

      return await response.json();
    },

    cancel: (c) => {
      c.vars.controller?.abort();
    }
  }
});
```

See [Actor Shutdown Abort Signal](/docs/actors/lifecycle#actor-shutdown-abort-signal) for automatically canceling operations when the actor stops.

## Using `ActionContext` Externally

When writing complex logic for actions, you may want to extract parts of your implementation into separate helper functions. When doing this, you'll need a way to properly type the context parameter.

Rivet provides the `ActionContextOf` utility type for exactly this purpose:

```typescript
import { actor, ActionContextOf } from "rivetkit";

const counter = actor({
  state: { count: 0 },
  
  actions: {
    increment: (c) => {
      incrementCount(c);
    }
  }
});

// Simple helper function with typed context
function incrementCount(c: ActionContextOf<typeof counter>) {
  c.state.count += 1;
}
```

See [types](/docs/actors/types) for more details on using `ActionContextOf` and other utility types.

## API Reference

- [`Actions`](/typedoc/interfaces/rivetkit.mod.Actions.html) - Interface for defining actions
- [`ActionContext`](/typedoc/interfaces/rivetkit.mod.ActionContext.html) - Context available in action handlers
- [`ActorDefinition`](/typedoc/interfaces/rivetkit.mod.ActorDefinition.html) - Interface for defining actors with actions
- [`ActorHandle`](/typedoc/types/rivetkit.client_mod.ActorHandle.html) - Handle for calling actions from client
- [`ActorActionFunction`](/typedoc/types/rivetkit.client_mod.ActorActionFunction.html) - Type for action functions

_Source doc path: /docs/actors/actions_

```

### reference/actors/keys.md

```markdown
# Actor Keys

> Source: `src/content/docs/actors/keys.mdx`
> Canonical URL: https://rivet.dev/docs/actors/keys
> Description: Actor keys uniquely identify actor instances within each actor type. Keys are used for addressing which specific actor to communicate with.

---
## Key Format

Actor keys can be either a string or an array of strings:

```typescript
import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

const counter = actor({
  state: { count: 0 },
  actions: { increment: (c) => c.state.count++ }
});

const chatRoom = actor({
  state: { messages: [] as string[] },
  actions: {}
});

const registry = setup({ use: { counter, chatRoom } });
const client = createClient<typeof registry>();

// String key
const counterHandle = client.counter.getOrCreate(["my-counter"]);

// Array key (compound key)
const chatRoomHandle = client.chatRoom.getOrCreate(["room", "general"]);
```

### Compound Keys & User Data

Array keys are useful when you need compound keys with user-provided data. Using arrays makes adding user data safe by preventing key injection attacks:

```typescript
import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

const chatRoom = actor({ state: { messages: [] as string[] }, actions: {} });
const gameRoom = actor({ state: { players: [] as string[] }, actions: {} });
const workspace = actor({ state: { data: {} }, actions: {} });

const registry = setup({ use: { chatRoom, gameRoom, workspace } });
const client = createClient<typeof registry>();

// Example user data
const userId = "user-123";
const gameId = "game-456";
const tenantId = "tenant-789";
const workspaceId = "workspace-abc";

// User-specific chat rooms
const userRoomHandle = client.chatRoom.getOrCreate(["user", userId, "private"]);

// Game rooms by region and difficulty
const gameRoomHandle = client.gameRoom.getOrCreate(["us-west", "hard", gameId]);

// Multi-tenant resources
const workspaceHandle = client.workspace.getOrCreate(["tenant", tenantId, workspaceId]);
```

This allows you to create hierarchical addressing schemes and organize actors by multiple dimensions.

Don't build keys using string interpolation like `"foo:${userId}:bar"` when `userId` contains user data. If a user provides a value containing the delimiter (`:` in this example), it can break your key structure and cause key injection attacks.

### Omitting Keys

You can create actors without specifying a key in situations where there is a singleton actor (i.e. only one actor of a given type). For example:

```typescript
import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

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

const registry = setup({ use: { globalActor } });
const client = createClient<typeof registry>();

// Get the singleton session
const globalActorHandle = client.globalActor.getOrCreate();
```

This pattern should be avoided, since a singleton actor usually means you have a single actor serving all traffic & your application will not scale. See [scaling documentation](/docs/actors/scaling) for more information.

### Key Uniqueness

Keys are unique within each actor name. Different actor types can use the same key:

```typescript
import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

const chatRoom = actor({ state: { messages: [] as string[] }, actions: {} });
const userProfile = actor({ state: { name: "" }, actions: {} });

const registry = setup({ use: { chatRoom, userProfile } });
const client = createClient<typeof registry>();

// These are different actors, same key is fine
const userChat = client.chatRoom.getOrCreate(["user-123"]);
const userProfileHandle = client.userProfile.getOrCreate(["user-123"]);
```

## Accessing Keys in Metadata

Access the actor's key within the actor using the [metadata](/docs/actors/metadata) API:

```typescript {{"title":"registry.ts"}}
import { actor, setup } from "rivetkit";

const chatRoom = actor({
  state: { messages: [] as string[] },
  actions: {
    getRoomName: (c) => {
      // Access the key from metadata
      const key = c.key;
      return key[1]; // Get "general" from ["room", "general"]
    }
  }
});

export const registry = setup({
  use: { chatRoom }
});
```

```typescript {{"title":"client.ts"}}
import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

const chatRoom = actor({
  state: { messages: [] as string[] },
  actions: { getRoomName: (c) => c.key[1] }
});

const registry = setup({ use: { chatRoom } });
const client = createClient<typeof registry>("http://localhost:8080");

async function connectToRoom(roomName: string) {
  // Connect to a chat room
  const chatRoomHandle = client.chatRoom.getOrCreate(["room", roomName]);

  // Get the room name from the key
  const retrievedRoomName = await chatRoomHandle.getRoomName();
  console.log("Room name:", retrievedRoomName); // e.g., "general"

  return chatRoomHandle;
}

// Usage example
const generalRoom = await connectToRoom("general");
```

## Configuration Examples

### Simple Configuration with Keys

Use keys to provide basic actor configuration:

```typescript {{"title":"registry.ts"}}
import { actor, setup } from "rivetkit";

interface UserSessionState {
  userId: string;
  loginTime: number;
  preferences: Record<string, unknown>;
}

const userSession = actor({
  state: { userId: "", loginTime: 0, preferences: {} } as UserSessionState,
  createState: (c): UserSessionState => ({
    userId: c.key[0], // Extract user ID from key
    loginTime: Date.now(),
    preferences: {}
  }),

  actions: {
    getUserId: (c) => c.state.userId
  }
});

export const registry = setup({
  use: { userSession }
});
```

```typescript {{"title":"client.ts"}}
import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

const userSession = actor({
  state: { userId: "", loginTime: 0, preferences: {} },
  actions: { getUserId: (c) => c.state.userId }
});

const registry = setup({ use: { userSession } });
const client = createClient<typeof registry>("http://localhost:8080");

// Pass user ID in the key for user-specific actors
const userId = "user-123";
const userSessionHandle = client.userSession.getOrCreate([userId]);
```

### Complex Configuration with Input

For more complex configuration, use [input parameters](/docs/actors/input):

```typescript {{"title":"client.ts"}}
import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

interface ChatRoomInput {
  maxUsers: number;
  isPrivate: boolean;
  moderators: string[];
  settings: { allowImages: boolean; slowMode: boolean };
}

const chatRoom = actor({
  state: { maxUsers: 0, isPrivate: false, moderators: [] as string[], settings: { allowImages: true, slowMode: false } },
  createState: (c, input: ChatRoomInput) => ({
    maxUsers: input.maxUsers,
    isPrivate: input.isPrivate,
    moderators: input.moderators,
    settings: input.settings,
  }),
  actions: {}
});

const registry = setup({ use: { chatRoom } });
const client = createClient<typeof registry>("http://localhost:8080");
const roomName = "general";

// Create with both key and input
const chatRoomHandle = await client.chatRoom.create(["room", roomName], {
  input: {
    maxUsers: 100,
    isPrivate: false,
    moderators: ["admin1", "admin2"],
    settings: {
      allowImages: true,
      slowMode: false
    }
  }
});
```

## API Reference

- [`ActorKey`](/typedoc/types/rivetkit.mod.ActorKey.html) - Key type for actors
- [`ActorQuery`](/typedoc/types/rivetkit.mod.ActorQuery.html) - Query type using keys
- [`GetOptions`](/typedoc/interfaces/rivetkit.client_mod.GetOptions.html) - Options for getting by key
- [`QueryOptions`](/typedoc/interfaces/rivetkit.client_mod.QueryOptions.html) - Options for querying

_Source doc path: /docs/actors/keys_

```

### reference/actors/schedule.md

```markdown
# Actor Scheduling

> Source: `src/content/docs/actors/schedule.mdx`
> Canonical URL: https://rivet.dev/docs/actors/schedule
> Description: Schedule actor actions in the future with persistent timers that survive restarts and upgrades.

---
Scheduling is used to trigger events in the future. The actor scheduler is like `setTimeout`, except the timeout will persist even if the actor restarts, upgrades, or crashes.

## Use Cases

Scheduling is helpful for long-running timeouts like month-long billing periods or account trials.

## Scheduling

### `c.schedule.after(duration, actionName, ...args)`

Schedules a function to be executed after a specified duration. This function persists across actor restarts, upgrades, or crashes.

Parameters:

- `duration` (number): The delay in milliseconds.
- `actionName` (string): The name of the action to be executed.
- `...args` (unknown[]): Additional arguments to pass to the function.

### `c.schedule.at(timestamp, actionName, ...args)`

Schedules a function to be executed at a specific timestamp. This function persists across actor restarts, upgrades, or crashes.

Parameters:

- `timestamp` (number): The exact time in milliseconds since the Unix epoch when the function should be executed.
- `actionName` (string): The name of the action to be executed.
- `...args` (unknown[]): Additional arguments to pass to the function.

## Full Example

```typescript
import { actor } from "rivetkit";

interface Reminder {
  userId: string;
  message: string;
  scheduledFor: number;
}

interface ReminderState {
  reminders: Record<string, Reminder>;
}

// Mock email function
function sendEmail(to: string, message: string) {
  console.log(`Sending email to ${to}: ${message}`);
}

const reminderService = actor({
  state: { reminders: {} } as ReminderState,

  actions: {
    setReminder: (c, userId: string, message: string, delayMs: number) => {
      const reminderId = crypto.randomUUID();

      // Store the reminder in state
      c.state.reminders[reminderId] = {
        userId,
        message,
        scheduledFor: Date.now() + delayMs
      };

      // Schedule the sendReminder action to run after the delay
      c.schedule.after(delayMs, "sendReminder", reminderId);

      return { reminderId };
    },

    sendReminder: (c, reminderId: string) => {
      const reminder = c.state.reminders[reminderId];
      if (!reminder) return;

      // Send reminder notification
      if (c.conns.size > 0) {
        // Send the reminder to all connected clients
        for (const conn of c.conns.values()) {
          conn.send("reminder", {
            message: reminder.message,
            scheduledAt: reminder.scheduledFor
          });
        }
      } else {
        // User is offline, send an email notification
        sendEmail(reminder.userId, reminder.message);
      }

      // Clean up the processed reminder
      delete c.state.reminders[reminderId];
    }
  }
});
```

_Source doc path: /docs/actors/schedule_

```

### reference/actors/ai-and-user-generated-actors.md

```markdown
# AI and User-Generated Rivet Actors

> Source: `src/content/docs/actors/ai-and-user-generated-actors.mdx`
> Canonical URL: https://rivet.dev/docs/actors/ai-and-user-generated-actors
> Description: This guide shows you how to programmatically create sandboxed Rivet environments and deploy custom actor code to them.

---
- [View Example on GitHub](https://github.com/rivet-dev/rivet/tree/main/examples/ai-and-user-generated-actors-freestyle) — Complete example showing how to deploy user-generated Rivet Actor code.

## Use Cases

Deploying AI and user-generated Rivet Actors to sandboxed namespaces is useful for:

- **AI-generated code deployments**: Deploy code generated by LLMs in sandboxed environments
- **User sandbox environments**: Give users their own sandboxed Rivet namespace to experiment
- **Preview deployments**: Create ephemeral environments for testing pull requests
- **Multi-tenant applications**: Isolate each customer in their own sandboxed namespace

## Rivet Actors For AI-Generated Backends

Traditional architectures require AI agents to coordinate across multiple disconnected systems: a database schemas, API logic, and synchronizing schemas & APIs.

With Rivet Actors, **state and logic live together in a single actor definition**. This consolidation means:

- **Less LLM context required**: No need to understand multiple systems or keep them in sync
- **Fewer errors**: State and behavior can't drift apart when they're defined together
- **More powerful generation**: AI agents can focus on business logic instead of infrastructure plumbing

## How It Works

The deployment process involves four key steps:

1. **Create sandboxed Rivet namespace**: Programmatically create a sandboxed Rivet namespace using the Cloud API or self-hosted Rivet API
2. **Generate tokens**: Create the necessary tokens for authentication:
   - **Runner token**: Authenticates the serverless runner to execute actors
   - **Publishable token**: Used by frontend clients to connect to actors
   - **Access token**: Provides API access for configuring the namespace
3. **Deploy AI or user-generated code**: Deploy the actor code and frontend programmatically to your serverless platform of choice (such as Vercel, Netlify, AWS Lambda, or any other provider). We'll be using [Freestyle](https://freestyle.sh) for this example since it's built for this use case.
4. **Connect Rivet to your deployed code**: Configure Rivet to run actors on your deployment in your sandboxed namespace

## Setup

	
### Rivet Cloud

		

			
### Prerequisites

				Before you begin, ensure you have:
				- Node.js 18+ installed
				- A [Freestyle](https://freestyle.sh) account and API token
				- A [Rivet Cloud](https://dashboard.rivet.dev/) account
			

			
### Create Cloud API Token

				1. Visit your project on [Rivet Cloud](https://dashboard.rivet.dev/)
				2. Click on "Tokens" in the sidebar
				3. Under "Cloud API Tokens" click "Create Token"
				4. Copy the token for use in your deployment script
			

			
### Install Dependencies

				Install the required dependencies:

				```bash
				npm install @rivetkit/engine-api-full@^25.7.2 freestyle-sandboxes@^0.0.95
				```
			

			
### Write Deployment Code

				Write deployment code that handles namespace creation, token generation, Freestyle deployment, and runner configuration. This can be called from your backend to deploy actor and frontend code to an isolated Rivet namespace.

				```typescript
				import { execSync } from "child_process";
				import { RivetClient } from "@rivetkit/engine-api-full";
				import { FreestyleSandboxes } from "freestyle-sandboxes";
				import { prepareDirForDeploymentSync } from "freestyle-sandboxes/utils";

				const CLOUD_API_TOKEN = "your-cloud-api-token";
				const FREESTYLE_DOMAIN = "your-app.style.dev";
				const FREESTYLE_API_KEY = "your-freestyle-api-key";

				async function deploy(projectDir: string) {
					// Step 1: Inspect API token to get project and organization
					const { project, organization } = await cloudRequest("GET", "/tokens/api/inspect");

					// Step 2: Create sandboxed namespace with a unique name
					const namespaceName = `ns-${Date.now()}-${Math.random().toString(36).substring(2, 8)}`;

					const { namespace } = await cloudRequest(
						"POST",
						`/projects/${project}/namespaces?org=${organization}`,
						{ displayName: namespaceName.substring(0, 16) },
					);
					const engineNamespaceName = namespace.access.engineNamespaceName;  // NOTE: Intentionally different than namespace.name

					// Step 3: Generate tokens
					// - Runner token: authenticates the serverless runner to execute actors
					// - Publishable token: used by frontend clients to connect to actors
					// - Access token: provides API access for configuring the namespace
					const { token: runnerToken } = await cloudRequest(
						"POST",
						`/projects/${project}/namespaces/${namespace.name}/tokens/secret?org=${organization}`,
					);

					const { token: publishableToken } = await cloudRequest(
						"POST",
						`/projects/${project}/namespaces/${namespace.name}/tokens/publishable?org=${organization}`,
					);

					const { token: accessToken } = await cloudRequest(
						"POST",
						`/projects/${project}/namespaces/${namespace.name}/tokens/access?org=${organization}`,
					);

					// Step 4: Build the frontend with public environment variables.
					execSync("npm run build", {
						cwd: projectDir,
						env: {
							...process.env,
							VITE_RIVET_ENDPOINT: "https://api.rivet.dev",
							VITE_RIVET_NAMESPACE: engineNamespaceName,
							VITE_RIVET_TOKEN: publishableToken,
						},
						stdio: "inherit",
					});

					// Step 5: Deploy actor code and frontend to Freestyle with backend
					// environment variables.
					const freestyle = new FreestyleSandboxes({ apiKey: FREESTYLE_API_KEY });
					const deploymentSource = prepareDirForDeploymentSync(projectDir);

					const { deploymentId } = await freestyle.deployWeb(deploymentSource, {
						envVars: {
							RIVET_ENDPOINT: "https://api.rivet.dev",
							RIVET_NAMESPACE: engineNamespaceName,
							RIVET_TOKEN: runnerToken,
						},
						entrypoint: "src/backend/server.ts",
						domains: [FREESTYLE_DOMAIN],
						build: false,
					});

					// Step 6: Configure Rivet to run actors on the Freestyle deployment.
					const rivet = new RivetClient({
						environment: "https://api.rivet.dev",
						token: accessToken,
					});

					await rivet.runnerConfigsUpsert("default", {
						datacenters: {
							"us-west-1": { // Freestyle datacenter is on west coast
								serverless: {
									url: `https://${FREESTYLE_DOMAIN}/api/rivet`,
									headers: {},
									runnersMargin: 0,
									minRunners: 0,
									maxRunners: 1000,
									slotsPerRunner: 1,
									requestLifespan: 60 * 5,
								},
							},
						},
						namespace: engineNamespaceName,
					});

					console.log("Deployment complete!");
					console.log("Frontend:", `https://${FREESTYLE_DOMAIN}`);
					console.log("Rivet Dashboard:", `https://dashboard.rivet.dev/orgs/${organization}/projects/${project}/ns/${namespace.name}`);
					console.log("Freestyle Dashboard:", `https://admin.freestyle.sh/dashboard/deployments/${deploymentId}`);
				}

				async function cloudRequest(method: string, path: string, body?: any) {
					const res = await fetch(`https://api-cloud.rivet.dev${path}`, {
						method,
						headers: {
							Authorization: `Bearer ${CLOUD_API_TOKEN}`,
							...(body && { "Content-Type": "application/json" }),
						},
						...(body && { body: JSON.stringify(body) }),
					});
					return res.json();
				}
				```

				See the [example repository](https://github.com/rivet-dev/rivet/tree/main/examples/ai-and-user-generated-actors-freestyle) for the complete project structure including the template directory and build process.

				For more information on Freestyle deployment, see the [Freestyle documentation](https://docs.freestyle.sh/web/overview).
			

		

	

	
### Rivet Self-Hosted

		

			
### Prerequisites

				Before you begin, ensure you have:
				- Node.js 18+ installed
				- A [Freestyle](https://freestyle.sh) account and API key
				- A [self-hosted Rivet instance](/docs/self-hosting) with endpoint and API token
			

			
### Install Dependencies

				Install the required dependencies:

				```bash
				npm install @rivetkit/engine-api-full@^25.7.2 freestyle-sandboxes@^0.0.95
				```
			

			
### Write Deployment Code

				Write deployment code that handles namespace creation, Freestyle deployment, and runner configuration. This can be called from your backend to deploy actor and frontend code to an isolated Rivet namespace.

				```typescript
				import { execSync } from "child_process";
				import { RivetClient } from "@rivetkit/engine-api-full";
				import { FreestyleSandboxes } from "freestyle-sandboxes";
				import { prepareDirForDeploymentSync } from "freestyle-sandboxes/utils";

				// Configuration
				const RIVET_ENDPOINT = "http://your-rivet-instance:6420";
				const RIVET_TOKEN = "your-rivet-token";
				const FREESTYLE_DOMAIN = "your-app.style.dev";
				const FREESTYLE_API_KEY = "your-freestyle-api-key";

				async function deploy(projectDir: string) {
					// Step 1: Create sandboxed namespace using the self-hosted Rivet API
					const rivet = new RivetClient({
						environment: RIVET_ENDPOINT,
						token: RIVET_TOKEN,
					});

					const namespaceName = `ns-${Date.now()}-${Math.random().toString(36).substring(2, 8)}`;

					const { namespace } = await rivet.namespaces.create({
						displayName: namespaceName,
						name: namespaceName,
					});

					// Step 2: Build the frontend with public environment variables.
					execSync("npm run build", {
						cwd: projectDir,
						env: {
							...process.env,
							VITE_RIVET_ENDPOINT: RIVET_ENDPOINT,
							VITE_RIVET_NAMESPACE: namespace.name,
							VITE_RIVET_TOKEN: RIVET_TOKEN,
						},
						stdio: "inherit",
					});

					// Step 3: Deploy actor and frontend to Freestyle with backend
					// environment variables.
					const freestyle = new FreestyleSandboxes({ apiKey: FREESTYLE_API_KEY });
					const deploymentSource = prepareDirForDeploymentSync(projectDir);

					const { deploymentId } = await freestyle.deployWeb(deploymentSource, {
						envVars: {
							RIVET_ENDPOINT,
							RIVET_NAMESPACE: namespace.name,
							RIVET_TOKEN,
						},
						entrypoint: "src/backend/server.ts",
						domains: [FREESTYLE_DOMAIN],
						build: false,
					});

					// Step 4: Configure your self-hosted Rivet to run actors on the Freestyle
					// deployment
					await rivet.runnerConfigsUpsert("default", {
						datacenters: {
							"us-west-1": { // Freestyle datacenter is on west coast
								serverless: {
									url: `https://${FREESTYLE_DOMAIN}/api/rivet`,
									headers: {},
									runnersMargin: 0,
									minRunners: 0,
									maxRunners: 1000,
									slotsPerRunner: 1,
									requestLifespan: 60 * 5,
								},
							},
						},
						namespace: namespace.name,
					});

					console.log("Deployment complete!");
					console.log("Frontend:", `https://${FREESTYLE_DOMAIN}`);
					console.log("Freestyle Dashboard:", `https://admin.freestyle.sh/dashboard/deployments/${deploymentId}`);
				}
				```

				See the [example repository](https://github.com/rivet-dev/rivet/tree/main/examples/ai-and-user-generated-actors-freestyle) for the complete project structure including the template directory and build process.

_Source doc path: /docs/actors/ai-and-user-generated-actors_

```

### reference/actors/authentication.md

```markdown
# Authentication

> Source: `src/content/docs/actors/authentication.mdx`
> Canonical URL: https://rivet.dev/docs/actors/authentication
> Description: Secure your actors with authentication and authorization.

---
## Do You Need Authentication?

### Rivet Cloud

	Actors are private by default on Rivet Cloud. Only requests with the publishable token can interact with actors.

	- **Backend-only actors**: If your publishable token is only included in your backend, then authentication is not necessary.
	- **Frontend-accessible actors**: If your publishable token is included in your frontend, then implementing authentication is recommended.

### Self-Hosted

	Actors are public by default on self-hosted Rivet. Anyone can access them without a token.

	- **Only accessible within private network**: If Rivet is only accessible within your private network, then authentication is not necessary.
	- **Rivet exposed to the public internet**: If Rivet is configured to accept traffic from the public internet, then implementing authentication is recommended.

## Authentication Connections

Authentication is configured through either:

- `onBeforeConnect` for simple pass/fail validation
- `createConnState` when you need to access user data in your actions via `c.conn.state`

### `onBeforeConnect`

The `onBeforeConnect` hook validates credentials before allowing a connection. Throw an error to reject the connection.

```typescript
import { actor, UserError } from "rivetkit";

interface ConnParams {
  authToken: string;
}

// Example token validation function
async function validateToken(token: string, roomKey: string[]): Promise<boolean> {
  // In production, verify JWT or call auth service
  return token.length > 0 && roomKey.length > 0;
}

interface Message {
  text: string;
  timestamp: number;
}

const chatRoom = actor({
  state: { messages: [] as Message[] },

  onBeforeConnect: async (c, params: ConnParams) => {
    const roomName = c.key;
    const isValid = await validateToken(params.authToken, roomName);
    if (!isValid) {
      throw new UserError("Forbidden", { code: "forbidden" });
    }
  },

  actions: {
    sendMessage: (c, text: string) => {
      c.state.messages.push({ text, timestamp: Date.now() });
    },
  },
});
```

### `createConnState`

Use `createConnState` to extract user data from credentials and store it in connection state. This data is accessible in actions via `c.conn.state`. Like `onBeforeConnect`, throwing an error will reject the connection. See [connections](/docs/actors/connections) for more details.

```typescript
import { actor, UserError } from "rivetkit";

interface ConnParams {
  authToken: string;
}

interface ConnState {
  userId: string;
  role: string;
}

interface Message {
  userId: string;
  text: string;
  timestamp: number;
}

// Example token validation function
async function validateToken(token: string, roomKey: string[]): Promise<{ sub: string; role: string } | null> {
  // In production, verify JWT or call auth service
  if (token.length > 0 && roomKey.length > 0) {
    return { sub: "user-123", role: "member" };
  }
  return null;
}

const chatRoom = actor({
  state: { messages: [] as Message[] },

  createConnState: async (c, params: ConnParams): Promise<ConnState> => {
    const roomName = c.key;
    const payload = await validateToken(params.authToken, roomName);
    if (!payload) {
      throw new UserError("Forbidden", { code: "forbidden" });
    }
    return {
      userId: payload.sub,
      role: payload.role,
    };
  },

  actions: {
    sendMessage: (c, text: string) => {
      // Access user data via c.conn.state
      const { userId, role } = c.conn.state;

      if (role !== "member") {
        throw new UserError("Insufficient permissions", { code: "insufficient_permissions" });
      }

      c.state.messages.push({ userId, text, timestamp: Date.now() });
      c.broadcast("newMessage", { userId, text });
    },
  },
});
```

## Available Auth Data

Authentication hooks have access to several properties:

| Property | Description |
|----------|-------------|
| `params` | Custom data passed by the client when connecting (see [connection params](/docs/actors/connections#extracting-data-from-connection-params)) |
| `c.request` | The underlying HTTP request object |
| `c.request.headers` | Request headers for tokens, API keys (does not work for `.connect()`) |
| `c.state` | Actor state for authorization decisions (see [state](/docs/actors/state)) |
| `c.key` | The actor's key (see [keys](/docs/actors/keys)) |

It's recommended to use `params` instead of `c.request.headers` whenever possible since it works for both HTTP & WebSocket connections.

## Client Usage

### Passing Credentials

Pass authentication data when connecting:

```typescript {{"title":"Connection"}}
import { createClient } from "rivetkit/client";

const client = createClient();
const chat = client.chatRoom.getOrCreate(["general"], {
  params: { authToken: "jwt-token-here" },
});

// Authentication will happen on connect by reading connection parameters
const connection = chat.connect();
```

```typescript {{"title":"Stateless Action"}}
import { createClient } from "rivetkit/client";

const client = createClient();
const chat = client.chatRoom.getOrCreate(["general"], {
  params: { authToken: "jwt-token-here" },
});

// Authentication will happen when calling the action by reading input
// parameters
await chat.sendMessage("Hello, world!");
```

```typescript {{"title":"HTTP Headers"}}
import { createClient } from "rivetkit/client";

// This only works for stateless actions, not WebSockets
const client = createClient({
  headers: {
    Authorization: "Bearer my-token",
  },
});

const chat = client.chatRoom.getOrCreate(["general"]);

// Authentication will happen when calling the action by reading headers
await chat.sendMessage("Hello, world!");
```

### Handling Errors

Authentication errors use the same system as regular errors. See [errors](/docs/actors/errors) for more details.

```typescript Connection
import { actor, setup } from "rivetkit";
import { ActorError, createClient } from "rivetkit/client";

// Define actor with protected action
const myActor = actor({
  state: {},
  actions: {
    protectedAction: (c) => ({ success: true })
  }
});

const registry = setup({ use: { myActor } });
const client = createClient<typeof registry>();
const actorHandle = await client.myActor.getOrCreate();

// Helper to show errors
function showError(message: string) {
  console.error(message);
}

const conn = actorHandle.connect();
conn.on("error", (error: ActorError) => {
  if (error.code === "forbidden") {
    window.location.href = "/login";
  } else if (error.code === "insufficient_permissions") {
    showError("You don't have permission for this action");
  }
});
```

```typescript Stateless-Action
import { actor, setup } from "rivetkit";
import { ActorError, createClient } from "rivetkit/client";

// Define actor with protected action
const myActor = actor({
  state: {},
  actions: {
    protectedAction: (c) => ({ success: true })
  }
});

const registry = setup({ use: { myActor } });
const client = createClient<typeof registry>();
const actorHandle = await client.myActor.getOrCreate();

// Helper to show errors
function showError(message: string) {
  console.error(message);
}

try {
  const result = await actorHandle.protectedAction();
} catch (error) {
  if (error instanceof ActorError && error.code === "forbidden") {
    window.location.href = "/login";
  } else if (error instanceof ActorError && error.code === "insufficient_permissions") {
    showError("You don't have permission for this action");
  }
}
```

## Examples

### JWT

Validate JSON Web Tokens and extract user claims:

```typescript
import { actor, UserError } from "rivetkit";

interface ConnParams {
  token: string;
}

interface ConnState {
  userId: string;
  role: string;
  permissions: string[];
}

interface JwtPayload {
  sub: string;
  role: string;
  permissions?: string[];
}

// Example JWT verification function - in production use a JWT library
function verifyJwt(token: string, secret: string): JwtPayload {
  // This is a simplified example - use jsonwebtoken or similar in production
  const parts = token.split(".");
  if (parts.length !== 3) throw new Error("Invalid token");
  const payload = JSON.parse(atob(parts[1])) as JwtPayload;
  return payload;
}

const jwtActor = actor({
  state: {},

  createConnState: (c, params: ConnParams): ConnState => {
    try {
      const payload = verifyJwt(params.token, process.env.JWT_SECRET || "secret");
      return {
        userId: payload.sub,
        role: payload.role,
        permissions: payload.permissions || [],
      };
    } catch {
      throw new UserError("Invalid or expired token", { code: "invalid_token" });
    }
  },

  actions: {
    protectedAction: (c) => {
      if (!c.conn.state.permissions.includes("write")) {
        throw new UserError("Write permission required", { code: "forbidden" });
      }
      return { success: true };
    },
  },
});
```

### External Auth Provider

Validate credentials against an external authentication service:

```typescript
import { actor, UserError } from "rivetkit";

interface ConnParams {
  apiKey: string;
}

interface ConnState {
  userId: string;
  tier: string;
}

const apiActor = actor({
  state: {},

  createConnState: async (c, params: ConnParams): Promise<ConnState> => {
    const response = await fetch(`https://api.my-auth-provider.com/validate`, {
      method: "POST",
      headers: { "X-API-Key": params.apiKey },
    });

    if (!response.ok) {
      throw new UserError("Invalid API key", { code: "invalid_api_key" });
    }

    const data = await response.json();
    return { userId: data.id, tier: data.tier };
  },

  actions: {
    premiumAction: (c) => {
      if (c.conn.state.tier !== "premium") {
        throw new UserError("Premium subscription required", { code: "forbidden" });
      }
      return "Premium content";
    },
  },
});
```

### Using `c.state` In Authorization

Access actor state via `c.state` and the actor's key via `c.key` to make authorization decisions:

```typescript
import { actor, UserError } from "rivetkit";

interface ConnParams {
  userId?: string;
}

const userProfile = actor({
  state: {
    ownerId: "user-123",
    isPrivate: true,
  },

  onBeforeConnect: (c, params: ConnParams) => {
    // Use actor state to check access permissions
    if (c.state.isPrivate && params.userId !== c.state.ownerId) {
      throw new UserError("Access denied to private profile", { code: "forbidden" });
    }
  },

  actions: {
    getProfile: (c) => ({ ownerId: c.state.ownerId }),
  },
});
```

### Role-Based Access Control

Create helper functions for common authorization patterns:

```typescript
import { actor, UserError } from "rivetkit";

const ROLE_HIERARCHY = { user: 1, moderator: 2, admin: 3 };

interface ConnState {
  role: keyof typeof ROLE_HIERARCHY;
  permissions: string[];
}

// Example token validation function
async function validateToken(token: string): Promise<{ role: keyof typeof ROLE_HIERARCHY; permissions: string[] }> {
  // In production, verify JWT or call auth service
  return { role: "user", permissions: ["read", "edit_posts"] };
}

function requireRole(requiredRole: keyof typeof ROLE_HIERARCHY) {
  return (c: { conn: { state: ConnState } }) => {
    const userRole = c.conn.state.role;
    if (ROLE_HIERARCHY[userRole] < ROLE_HIERARCHY[requiredRole]) {
      throw new UserError(`${requiredRole} role required`, { code: "forbidden" });
    }
  };
}

function requirePermission(permission: string) {
  return (c: { conn: { state: ConnState } }) => {
    if (!c.conn.state.permissions?.includes(permission)) {
      throw new UserError(`Permission '${permission}' required`, { code: "forbidden" });
    }
  };
}

const forumActor = actor({
  state: {},

  createConnState: async (c, params: { token: string }): Promise<ConnState> => {
    const user = await validateToken(params.token);
    return { role: user.role, permissions: user.permissions };
  },

  actions: {
    deletePost: (c, postId: string) => {
      requireRole("moderator")(c);
      // Delete post...
    },

    editPost: (c, postId: string, content: string) => {
      requirePermission("edit_posts")(c);
      // Edit post...
    },
  },
});
```

### Rate Limiting

Use `c.vars` to track connection attempts and rate limit by user:

```typescript
import { actor, UserError } from "rivetkit";

interface ConnParams {
  authToken: string;
}

interface RateLimitEntry {
  count: number;
  resetAt: number;
}

// Example token validation function
async function validateToken(token: string): Promise<{ userId: string }> {
  // In production, verify JWT or call auth service
  return { userId: "user-123" };
}

const rateLimitedActor = actor({
  state: {},
  createVars: () => ({ rateLimits: {} as Record<string, RateLimitEntry> }),

  onBeforeConnect: async (c, params: ConnParams) => {
    // Extract user ID
    const { userId } = await validateToken(params.authToken);

    // Check rate limit
    const now = Date.now();
    const limit = c.vars.rateLimits[userId];

    if (limit && limit.resetAt > now && limit.count >= 10) {
      throw new UserError("Too many requests, try again later", { code: "rate_limited" });
    }

    // Update rate limit
    if (!limit || limit.resetAt <= now) {
      c.vars.rateLimits[userId] = { count: 1, resetAt: now + 60_000 };
    } else {
      limit.count++;
    }
  },

  actions: {
    getData: (c) => ({ success: true }),
  },
});
```

The limits in this example are [ephemeral](/docs/actors/state#ephemeral-variables-vars). If you wish to persist rate limits, you can optionally replace `vars` with `state`.

### Caching Tokens

Cache validated tokens in `c.vars` to avoid redundant validation on repeated connections. See [ephemeral variables](/docs/actors/state#ephemeral-variables-vars) for more details.

```typescript
import { actor, UserError } from "rivetkit";

interface ConnParams {
  authToken: string;
}

interface ConnState {
  userId: string;
  role: string;
}

interface TokenCache {
  [token: string]: {
    userId: string;
    role: string;
    expiresAt: number;
  };
}

// Example token validation function
async function validateToken(token: string): Promise<{ sub: string; role: string } | null> {
  // In production, verify JWT or call auth service
  if (token.length > 0) {
    return { sub: "user-123", role: "member" };
  }
  return null;
}

const cachedAuthActor = actor({
  state: {},
  createVars: () => ({ tokenCache: {} as TokenCache }),

  createConnState: async (c, params: ConnParams): Promise<ConnState> => {
    const token = params.authToken;

    // Check cache first
    const cached = c.vars.tokenCache[token];
    if (cached && cached.expiresAt > Date.now()) {
      return { userId: cached.userId, role: cached.role };
    }

    // Validate token (expensive operation)
    const payload = await validateToken(token);
    if (!payload) {
      throw new UserError("Invalid token", { code: "invalid_token" });
    }

    // Cache the result
    c.vars.tokenCache[token] = {
      userId: payload.sub,
      role: payload.role,
      expiresAt: Date.now() + 5 * 60 * 1000, // 5 minutes
    };

    return { userId: payload.sub, role: payload.role };
  },

  actions: {
    getData: (c) => ({ userId: c.conn.state.userId }),
  },
});
```

## API Reference

- [`AuthIntent`](/typedoc/types/rivetkit.mod.AuthIntent.html) - Authentication intent type
- [`BeforeConnectContext`](/typedoc/interfaces/rivetkit.mod.BeforeConnectContext.html) - Context for auth checks
- [`ConnectContext`](/typedoc/interfaces/rivetkit.mod.ConnectContext.html) - Context after connection

_Source doc path: /docs/actors/authentication_

```

### reference/actors/quickstart/cloudflare-workers.md

```markdown
# Cloudflare Workers Quickstart

> Source: `src/content/docs/actors/quickstart/cloudflare-workers.mdx`
> Canonical URL: https://rivet.dev/docs/actors/quickstart/cloudflare-workers
> Description: Get started with Rivet Actors on Cloudflare Workers with Durable Objects

---
### Add Rivet Skill to Coding Agent (Optional)

If you're using an AI coding assistant (like Claude Code, Cursor, Windsurf, etc.), add Rivet skills for enhanced development assistance:

```sh
npx skills add rivet-dev/skills
```

### Install Rivet

```sh
npm install rivetkit @rivetkit/cloudflare-workers
```

### Create an Actor

Create a simple counter actor:

```ts {{"title":"registry.ts"}}
import { actor, setup } from "rivetkit";

export const counter = actor({
	state: { count: 0 },
	actions: {
		increment: (c, x: number) => {
			c.state.count += x;
			c.broadcast("newCount", c.state.count);
			return c.state.count;
		},
	},
});

export const registry = setup({
	use: { counter },
});
```

### Setup Server

Choose your preferred web framework:

```ts {{"title":"registry.ts"}} @hide
import { actor, setup } from "rivetkit";

export const counter = actor({
	state: { count: 0 },
	actions: {
		increment: (c, x: number) => {
			c.state.count += x;
			c.broadcast("newCount", c.state.count);
			return c.state.count;
		},
	},
});

export const registry = setup({
	use: { counter },
});
```

```ts Default
import { createHandler } from "@rivetkit/cloudflare-workers";
import { registry } from "./registry";

// The `/api/rivet` endpoint is automatically exposed here for external clients
const { handler, ActorHandler } = createHandler(registry);
export { handler as default, ActorHandler };
```

```ts {{"title":"registry.ts"}} @hide
import { actor, setup } from "rivetkit";

export const counter = actor({
	state: { count: 0 },
	actions: {
		increment: (c, x: number) => {
			c.state.count += x;
			c.broadcast("newCount", c.state.count);
			return c.state.count;
		},
	},
});

export const registry = setup({
	use: { counter },
});
```

```ts Hono
import { createHandler, type Client } from "@rivetkit/cloudflare-workers";
import { Hono } from "hono";
import { registry } from "./registry";

const app = new Hono<{ Bindings: { RIVET: Client<typeof registry> } }>();

app.post("/increment/:name", async (c) => {
	const client = c.env.RIVET;
	const name = c.req.param("name");

	// Get or create actor and call action
	const counter = client.counter.getOrCreate([name]);
	const newCount = await counter.increment(1);

	return c.json({ count: newCount });
});

// The `/api/rivet` endpoint is automatically exposed here for external clients
const { handler, ActorHandler } = createHandler(registry, { fetch: app.fetch });
export { handler as default, ActorHandler };
```

```ts {{"title":"registry.ts"}} @hide
import { actor, setup } from "rivetkit";

export const counter = actor({
	state: { count: 0 },
	actions: {
		increment: (c, x: number) => {
			c.state.count += x;
			c.broadcast("newCount", c.state.count);
			return c.state.count;
		},
	},
});

export const registry = setup({
	use: { counter },
});
```

```ts Manual-Routing @nocheck
import { createHandler } from "@rivetkit/cloudflare-workers";
import { registry } from "./registry";

// The `/api/rivet` endpoint is automatically mounted on this router for external clients
const { handler, ActorHandler } = createHandler(registry, {
	fetch: async (request, env, ctx) => {
		const url = new URL(request.url);

		if (url.pathname.startsWith("/increment/")) {
			const name = url.pathname.split("/")[2];
			const client = env.RIVET;

			const counter = client.counter.getOrCreate([name]);
			const newCount = await counter.increment(1);

			return new Response(JSON.stringify({ count: newCount }), {
				headers: { "Content-Type": "application/json" },
			});
		}

		return new Response("Not Found", { status: 404 });
	}
});

export { handler as default, ActorHandler };
```

```ts {{"title":"registry.ts"}} @hide
import { actor, setup } from "rivetkit";

export const counter = actor({
	state: { count: 0 },
	actions: {
		increment: (c, x: number) => {
			c.state.count += x;
			c.broadcast("newCount", c.state.count);
			return c.state.count;
		},
	},
});

export const registry = setup({
	use: { counter },
});
```

```ts Advanced @nocheck
import { createInlineClient } from "@rivetkit/cloudflare-workers";
import { registry } from "./registry";

const {
	client,
	fetch: rivetFetch,
	ActorHandler,
} = createInlineClient(registry);

// IMPORTANT: Your Durable Object must be exported here
export { ActorHandler };

export default {
	fetch: async (request, env, ctx) => {
		const url = new URL(request.url);

		// Custom request handler
		if (request.method === "POST" && url.pathname.startsWith("/increment/")) {
			const name = url.pathname.slice("/increment/".length);

			const counter = client.counter.getOrCreate([name]);
			const newCount = await counter.increment(1);

			return new Response(JSON.stringify({ count: newCount }), {
				headers: { "Content-Type": "application/json" },
			});
		}

		// Optional: Mount /api/rivet path to access actors from external clients
		if (url.pathname.startsWith("/api/rivet")) {
			const strippedPath = url.pathname.substring("/api/rivet".length);
			url.pathname = strippedPath;
			const modifiedRequest = new Request(url.toString(), request);
			return rivetFetch(modifiedRequest, env, ctx);
		}

		return new Response("Not Found", { status: 404 });
	},
} satisfies ExportedHandler;
```

### Run Server

Configure your `wrangler.json` for Cloudflare Workers:

```json {{"title":"wrangler.json"}}
{
  "name": "my-rivetkit-app",
  "main": "src/index.ts",
  "compatibility_date": "2025-01-20",
  "compatibility_flags": ["nodejs_compat"],
  "migrations": [
    {
      "tag": "v1",
      "new_sqlite_classes": ["ActorHandler"]
    }
  ],
  "durable_objects": {
    "bindings": [
      {
        "name": "ACTOR_DO",
        "class_name": "ActorHandler"
      }
    ]
  },
  "kv_namespaces": [
    {
      "binding": "ACTOR_KV",
      "id": "your_namespace_id"
    }
  ]
}
```

Start the development server:

```sh
wrangler dev
```

Your server is now running at `http://localhost:8787`

### Test Your Actor

Test your counter actor using HTTP requests:

```ts {{"title":"JavaScript"}}
// Increment counter
const response = await fetch("http://localhost:8787/increment/my-counter", {
	method: "POST"
});

const result = await response.json();
console.log("Count:", result.count); // 1
```

```sh curl
# Increment counter
curl -X POST http://localhost:8787/increment/my-counter
```

### Deploy to Cloudflare Workers

Deploy to Cloudflare's global edge network:

```bash
wrangler deploy
```

Your actors will now run on Cloudflare's edge with persistent state backed by Durable Objects.

See the [Cloudflare Workers deployment guide](/docs/connect/cloudflare-workers) for detailed deployment instructions and configuration options.

## Configuration Options

### Connect To The Rivet Actor

Create a type-safe client to connect from your frontend or another service:

### JavaScript

```ts {{"title":"registry.ts"}} @hide
import { actor, setup } from "rivetkit";

export const counter = actor({
	state: { count: 0 },
	actions: {
		increment: (c, x: number) => {
			c.state.count += x;
			c.broadcast("newCount", c.state.count);
			return c.state.count;
		},
	},
});

export const registry = setup({
	use: { counter },
});
```

```ts {{"title":"client.ts"}}
import { createClient } from "rivetkit/client";
import type { registry } from "./registry";

// Create typed client (use your deployed URL)
const client = createClient<typeof registry>("https://your-app.workers.dev/api/rivet");

// Use the counter actor directly
const counter = client.counter.getOrCreate(["my-counter"]);

// Call actions
const count = await counter.increment(3);
console.log("New count:", count);

// Listen to real-time events
const connection = counter.connect();
connection.on("newCount", (newCount: number) => {
	console.log("Count changed:", newCount);
});

// Increment through connection
await connection.increment(1);
```

See the [JavaScript client documentation](/docs/clients/javascript) for more information.

### React

```ts {{"title":"registry.ts"}} @hide
import { actor, setup } from "rivetkit";

export const counter = actor({
	state: { count: 0 },
	actions: {
		increment: (c, x: number) => {
			c.state.count += x;
			c.broadcast("newCount", c.state.count);
			return c.state.count;
		},
	},
});

export const registry = setup({
	use: { counter },
});
```

```tsx {{"title":"Counter.tsx"}}
import { createRivetKit } from "@rivetkit/react";
import { useState } from "react";
import type { registry } from "./registry";

const { useActor } = createRivetKit<typeof registry>("https://your-app.workers.dev/api/rivet");

function Counter() {
	const [count, setCount] = useState(0);

	const counter = useActor({
		name: "counter",
		key: ["my-counter"]
	});

	counter.useEvent("newCount", (x: number) => setCount(x));

	const increment = async () => {
		await counter.connection?.increment(1);
	};

	return (
		<div>
			<p>Count: {count}</p>
			<button onClick={increment}>Increment</button>
		</div>
	);
}
```

See the [React documentation](/docs/clients/react) for more information.

	Cloudflare Workers mounts the Rivet endpoint on `/api/rivet` by default.

_Source doc path: /docs/actors/quickstart/cloudflare-workers_

```

### reference/actors/communicating-between-actors.md

```markdown
# Communicating Between Actors

> Source: `src/content/docs/actors/communicating-between-actors.mdx`
> Canonical URL: https://rivet.dev/docs/actors/communicating-between-actors
> Description: Learn how actors can call other actors and share data

---
Actors can communicate with each other using the server-side actor client, enabling complex workflows and data sharing between different actor instances.

We recommend reading the [clients documentation](/docs/clients) first. This guide focuses specifically on communication between actors.

## Using the Server-Side Actor Client

The server-side actor client allows actors to call other actors within the same registry. Access it via `c.client()` in your actor context:

```typescript
import { actor, setup } from "rivetkit";

interface Order {
  id: string;
  customerId: string;
  quantity: number;
  amount: number;
}

interface ProcessedOrder extends Order {
  status: string;
  paymentResult: { transactionId: string };
}

const inventory = actor({
  state: { stock: 100 },
  actions: {
    reserveStock: (c, quantity: number) => {
      c.state.stock -= quantity;
      return { reserved: quantity };
    }
  }
});

const payment = actor({
  state: {},
  actions: {
    processPayment: (c, amount: number) => ({ transactionId: "tx-123" })
  }
});

const orderProcessor = actor({
  state: { orders: [] as ProcessedOrder[] },

  actions: {
    processOrder: async (c, order: Order) => {
      const client = c.client<typeof registry>();

      // Reserve the stock
      const inventoryHandle = client.inventory.getOrCreate(["main"]);
      await inventoryHandle.reserveStock(order.quantity);

      // Process payment through payment actor
      const paymentHandle = client.payment.getOrCreate([order.customerId]);
      const result = await paymentHandle.processPayment(order.amount);

      // Update order state
      c.state.orders.push({ ...order, status: "completed", paymentResult: result });

      return { success: true, orderId: order.id };
    }
  }
});

const registry = setup({ use: { inventory, payment, orderProcessor } });
```

## Use Cases and Patterns

### Actor Orchestration

Use a coordinator actor to manage complex workflows:

```typescript
import { actor, setup } from "rivetkit";

interface WorkflowResult {
  workflowId: string;
  result: { finalized: boolean };
  completedAt: number;
}

const dataProcessor = actor({
  state: {},
  actions: {
    initialize: (c, workflowId: string) => ({ workflowId, data: "initialized" })
  }
});

const validator = actor({
  state: {},
  actions: {
    validate: (c, data: { workflowId: string; data: string }) => ({ valid: true, data })
  }
});

const finalizer = actor({
  state: {},
  actions: {
    finalize: (c, validationResult: { valid: boolean }) => ({ finalized: validationResult.valid })
  }
});

const workflowActor = actor({
  state: { workflows: [] as WorkflowResult[] },

  actions: {
    executeWorkflow: async (c, workflowId: string) => {
      const client = c.client<typeof registry>();

      // Step 1: Initialize data
      const dataProcessorHandle = client.dataProcessor.getOrCreate(["main"]);
      const data = await dataProcessorHandle.initialize(workflowId);

      // Step 2: Process through multiple actors
      const validatorHandle = client.validator.getOrCreate(["main"]);
      const validationResult = await validatorHandle.validate(data);

      // Step 3: Finalize
      const finalizerHandle = client.finalizer.getOrCreate(["main"]);
      const result = await finalizerHandle.finalize(validationResult);

      c.state.workflows.push({ workflowId, result, completedAt: Date.now() });
      return result;
    }
  }
});

const registry = setup({ use: { dataProcessor, validator, finalizer, workflowActor } });
```

### Data Aggregation

Collect data from multiple actors:

```typescript
import { actor, setup } from "rivetkit";

interface Stats {
  count: number;
  total: number;
}

interface Report {
  id: string;
  type: string;
  data: { users: Stats; orders: Stats; system: Stats };
  generatedAt: number;
}

const userMetrics = actor({
  state: {},
  actions: {
    getStats: (c): Stats => ({ count: 100, total: 500 })
  }
});

const orderMetrics = actor({
  state: {},
  actions: {
    getStats: (c): Stats => ({ count: 50, total: 10000 })
  }
});

const systemMetrics = actor({
  state: {},
  actions: {
    getStats: (c): Stats => ({ count: 5, total: 99 })
  }
});

const analyticsActor = actor({
  state: { reports: [] as Report[] },

  actions: {
    generateReport: async (c, reportType: string) => {
      const client = c.client<typeof registry>();

      // Collect data from multiple sources
      const userMetricsHandle = client.userMetrics.getOrCreate(["main"]);
      const orderMetricsHandle = client.orderMetrics.getOrCreate(["main"]);
      const systemMetricsHandle = client.systemMetrics.getOrCreate(["main"]);

      const [users, orders, system] = await Promise.all([
        userMetricsHandle.getStats(),
        orderMetricsHandle.getStats(),
        systemMetricsHandle.getStats()
      ]);

      const report: Report = {
        id: crypto.randomUUID(),
        type: reportType,
        data: { users, orders, system },
        generatedAt: Date.now()
      };

      c.state.reports.push(report);
      return report;
    }
  }
});

const registry = setup({ use: { userMetrics, orderMetrics, systemMetrics, analyticsActor } });
```

### Event-Driven Architecture

Use connections to listen for events from other actors:

```typescript
import { actor, setup } from "rivetkit";

interface User {
  id: string;
  name: string;
}

interface Order {
  id: string;
  amount: number;
}

interface AuditLog {
  event: string;
  data: User | Order;
  timestamp: number;
}

const userActor = actor({
  state: {},
  actions: {
    createUser: (c, name: string) => {
      const user = { id: crypto.randomUUID(), name };
      c.broadcast("userCreated", user);
      return user;
    }
  }
});

const orderActor = actor({
  state: {},
  actions: {
    completeOrder: (c, amount: number) => {
      const order = { id: crypto.randomUUID(), amount };
      c.broadcast("orderCompleted", order);
      return order;
    }
  }
});

const auditLogActor = actor({
  state: { logs: [] as AuditLog[] },

  actions: {
    startAuditing: async (c) => {
      const client = c.client<typeof registry>();

      // Connect to multiple actors to listen for events
      const userActorConn = client.userActor.getOrCreate(["main"]).connect();
      const orderActorConn = client.orderActor.getOrCreate(["main"]).connect();

      // Listen for user events
      userActorConn.on("userCreated", (user: User) => {
        c.state.logs.push({
          event: "userCreated",
          data: user,
          timestamp: Date.now()
        });
      });

      // Listen for order events
      orderActorConn.on("orderCompleted", (order: Order) => {
        c.state.logs.push({
          event: "orderCompleted",
          data: order,
          timestamp: Date.now()
        });
      });

      return { status: "auditing started" };
    }
  }
});

const registry = setup({ use: { userActor, orderActor, auditLogActor } });
```

### Batch Operations

Process multiple items in parallel:

```typescript
import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

interface Item {
  type: string;
  data: string;
}

const processor = actor({
  state: {},
  actions: {
    process: (c, item: Item) => ({ processed: true, item })
  }
});

const registry = setup({ use: { processor } });
const client = createClient<typeof registry>();

// Process items in parallel
const items: Item[] = [
  { type: "typeA", data: "data1" },
  { type: "typeB", data: "data2" }
];

const results = await Promise.all(
  items.map(item => client.processor.getOrCreate([item.type]).process(item))
);
```

## API Reference

- [`ActorHandle`](/typedoc/types/rivetkit.client_mod.ActorHandle.html) - Handle for calling other actors
- [`Client`](/typedoc/types/rivetkit.mod.Client.html) - Client type for actor communication
- [`ActorAccessor`](/typedoc/interfaces/rivetkit.client_mod.ActorAccessor.html) - Accessor for getting actor handles

_Source doc path: /docs/actors/communicating-between-actors_

```

### reference/actors/connections.md

```markdown
# Connections

> Source: `src/content/docs/actors/connections.mdx`
> Canonical URL: https://rivet.dev/docs/actors/connections
> Description: Connections represent client connections to your actor. They provide a way to handle client authentication, manage connection-specific data, and control the connection lifecycle.

---
For documentation on connecting to actors from clients, see the [Clients documentation](/docs/clients).

## Parameters

When clients connect to an actor, they can pass connection parameters that are handled during the connection process.

For example:

```typescript {{"title":"Client"}}
import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

interface ConnParams {
  authToken: string;
}

interface ConnState {
  userId: string;
  role: string;
}

const gameRoom = actor({
  state: {},
  createConnState: (c, params: ConnParams): ConnState => {
    return { userId: "user-123", role: "player" };
  },
  actions: {}
});

const registry = setup({ use: { gameRoom } });
const client = createClient<typeof registry>("http://localhost:8080");

const gameRoomHandle = client.gameRoom.getOrCreate(["room-123"], {
  params: { authToken: "supersekure" }
});
```

```typescript {{"title":"Actor"}}
import { actor } from "rivetkit";

interface ConnParams {
  authToken: string;
}

interface ConnState {
  userId: string;
  role: string;
}

// Example validation functions
function validateToken(token: string): boolean {
  return token.length > 0;
}

function getUserIdFromToken(token: string): string {
  return "user-" + token.slice(0, 8);
}

const gameRoom = actor({
  state: {},

  // Handle connection setup
  createConnState: (c, params: ConnParams): ConnState => {
    // Validate authentication token
    const authToken = params.authToken;

    if (!authToken || !validateToken(authToken)) {
      throw new Error("Invalid auth token");
    }

    // Create connection state
    return { userId: getUserIdFromToken(authToken), role: "player" };
  },

  actions: {}
});
```

## Connection State

There are two ways to define an actor's connection state:

	
### connState

		Define connection state as a constant value:

		```typescript
		import { actor } from "rivetkit";

		const chatRoom = actor({
		  state: { messages: [] },

		  // Define default connection state as a constant
		  connState: {
		    role: "guest",
		    joinedAt: 0
		  },

		  onConnect: (c) => {
		    // Update join timestamp when a client connects
		    c.conn.state.joinedAt = Date.now();
		  },

		  actions: {
		    // ...
		  }
		});
		```

		This value will be cloned for every new connection using `structuredClone`.
	

	
### createConnState

		Create connection state dynamically with a function called for each connection:

		```typescript
		import { actor } from "rivetkit";

		interface ConnState {
		  userId: string;
		  role: string;
		  joinedAt: number;
		}

		interface Message {
		  username: string;
		  message: string;
		}

		function generateUserId(): string {
		  return "user-" + Math.random().toString(36).slice(2, 11);
		}

		const chatRoom = actor({
		  state: { messages: [] as Message[] },

		  // Create connection state dynamically
		  createConnState: (c): ConnState => {
		    // Return the connection state
		    return {
		      userId: generateUserId(),
		      role: "guest",
		      joinedAt: Date.now()
		    };
		  },

		  actions: {
		    sendMessage: (c, message: string) => {
		      const username = c.conn.state.userId;
		      c.state.messages.push({ username, message });
		      c.broadcast("newMessage", { username, message });
		    }
		  }
		});
		```
	

## Connection Lifecycle

Each client connection goes through a series of lifecycle hooks that allow you to validate, initialize, and clean up connection-specific resources.

**On Connect** (per client)

- `onBeforeConnect`
- `createConnState`
- `onConnect`

**On Disconnect** (per client)

- `onDisconnect`

### `createConnState` and `connState`

[API Reference](/typedoc/interfaces/rivetkit.mod.CreateConnStateContext.html)

There are two ways to define the initial state for connections:
1. `connState`: Define a constant object that will be used as the initial state for all connections
2. `createConnState`: A function that dynamically creates initial connection state based on connection parameters. Can be async.

### `onBeforeConnect`

[API Reference](/typedoc/interfaces/rivetkit.mod.BeforeConnectContext.html)

The `onBeforeConnect` hook is called whenever a new client connects to the actor. Can be async. Clients can pass parameters when connecting, accessible via `params`. This hook is used for connection validation and can throw errors to reject connections.

The `onBeforeConnect` hook does NOT return connection state - it's used solely for validation.

```typescript
import { actor } from "rivetkit";

interface Message {
  text: string;
  author: string;
}

interface ConnParams {
  authToken?: string;
  userId?: string;
  role?: string;
}

interface ConnState {
  userId: string;
  role: string;
  joinTime: number;
}

function validateToken(token: string): boolean {
  return token.length > 0;
}

const chatRoom = actor({
  state: { messages: [] as Message[] },

  // Dynamically create connection state
  createConnState: (c, params: ConnParams): ConnState => {
    return {
      userId: params.userId || "anonymous",
      role: params.role || "guest",
      joinTime: Date.now()
    };
  },

  // Validate connections before accepting them
  onBeforeConnect: (c, params: ConnParams) => {
    // Validate authentication
    const authToken = params.authToken;
    if (!authToken || !validateToken(authToken)) {
      throw new Error("Invalid authentication");
    }

    // Authentication is valid, connection will proceed
    // The actual connection state will come from createConnState
  },

  actions: {}
});
```

Connections cannot interact with the actor until this method completes successfully. Throwing an error will abort the connection. This can be used for authentication, see [Authentication](/docs/actors/authentication) for details.

### `onConnect`

[API Reference](/typedoc/interfaces/rivetkit.mod.ConnectContext.html)

Executed after the client has successfully connected. Can be async. Receives the connection object as a second parameter.

```typescript
import { actor } from "rivetkit";

interface ConnState {
  userId: string;
}

interface UserStatus {
  online: boolean;
  lastSeen: number;
}

const chatRoom = actor({
  state: { users: {} as Record<string, UserStatus>, messages: [] as string[] },

  createConnState: (): ConnState => ({
    userId: "user-" + Math.random().toString(36).slice(2, 11)
  }),

  onConnect: (c, conn) => {
    // Add user to the room's user list using connection state
    const userId = conn.state.userId;
    c.state.users[userId] = {
      online: true,
      lastSeen: Date.now()
    };

    // Broadcast that a user joined
    c.broadcast("userJoined", { userId, timestamp: Date.now() });

    console.log(`User ${userId} connected`);
  },

  actions: {}
});
```

Messages will not be processed for this actor until this hook succeeds. Errors thrown from this hook will cause the client to disconnect.

### `onDisconnect`

[API Reference](/typedoc/interfaces/rivetkit.mod.ActorDefinition.html)

Called when a client disconnects from the actor. Can be async. Receives the connection object as a second parameter. Use this to clean up any connection-specific resources.

```typescript
import { actor } from "rivetkit";

interface ConnState {
  userId: string;
}

interface UserStatus {
  online: boolean;
  lastSeen: number;
}

const chatRoom = actor({
  state: { users: {} as Record<string, UserStatus>, messages: [] as string[] },

  createConnState: (): ConnState => ({
    userId: "user-" + Math.random().toString(36).slice(2, 11)
  }),

  onDisconnect: (c, conn) => {
    // Update user status when they disconnect
    const userId = conn.state.userId;
    if (c.state.users[userId]) {
      c.state.users[userId].online = false;
      c.state.users[userId].lastSeen = Date.now();
    }

    // Broadcast that a user left
    c.broadcast("userLeft", { userId, timestamp: Date.now() });

    console.log(`User ${userId} disconnected`);
  },

  actions: {}
});
```

## Connection List

All active connections can be accessed through the context object's `conns` property. This is an array of all current connections.

This is frequently used with `conn.send(name, event)` to send messages directly to clients. To send an event to all connections at once, use `c.broadcast()` instead. See [Events](/docs/actors/events) for more details on broadcasting.

For example:

```typescript
import { actor } from "rivetkit";

interface ConnState {
  userId: string;
}

const chatRoom = actor({
  state: { users: {} as Record<string, { online: boolean }> },

  createConnState: (): ConnState => ({
    userId: "user-" + Math.random().toString(36).slice(2, 11)
  }),

  actions: {
    sendDirectMessage: (c, recipientId: string, message: string) => {
      // Find the recipient's connection by iterating over the Map
      let recipientConn = null;
      for (const conn of c.conns.values()) {
        if (conn.state.userId === recipientId) {
          recipientConn = conn;
          break;
        }
      }

      if (recipientConn) {
        // Send a private message to just that client
        recipientConn.send("directMessage", {
          from: c.conn.state.userId,
          message: message
        });
      }
    }
  }
});
```

`conn.send()` has no effect on [low-level WebSocket connections](/docs/actors/websocket-handler). For low-level WebSockets, use the WebSocket API directly (e.g., `websocket.send()`).

## Disconnecting clients

Connections can be disconnected from within an action:

```typescript
import { actor } from "rivetkit";

interface ConnState {
  userId: string;
}

const secureRoom = actor({
  state: {},

  createConnState: (): ConnState => ({
    userId: "user-" + Math.random().toString(36).slice(2, 11)
  }),

  actions: {
    kickUser: (c, targetUserId: string, reason?: string) => {
      // Find the connection to kick by iterating over the Map
      for (const conn of c.conns.values()) {
        if (conn.state.userId === targetUserId) {
          // Disconnect with a reason
          conn.disconnect(reason || "Kicked by admin");
          break;
        }
      }
    }
  }
});
```

If you need to wait for the disconnection to complete, you can use `await`:

```typescript
import { actor } from "rivetkit";

const myActor = actor({
  state: {},
  actions: {
    disconnect: async (c) => {
      await c.conn.disconnect("Too many requests");
    }
  }
});
```

This ensures the underlying network connections close cleanly before continuing.

## API Reference

- [`Conn`](/typedoc/interfaces/rivetkit.mod.Conn.html) - Connection interface
- [`ConnInitContext`](/typedoc/interfaces/rivetkit.mod.ConnInitContext.html) - Connection initialization context
- [`CreateConnStateContext`](/typedoc/interfaces/rivetkit.mod.CreateConnStateContext.html) - Context for creating connection state
- [`BeforeConnectContext`](/typedoc/interfaces/rivetkit.mod.BeforeConnectContext.html) - Pre-connection lifecycle hook context
- [`ConnectContext`](/typedoc/interfaces/rivetkit.mod.ConnectContext.html) - Post-connection lifecycle hook context
- [`ActorConn`](/typedoc/types/rivetkit.client_mod.ActorConn.html) - Typed connection from client side

_Source doc path: /docs/actors/connections_

```

### reference/actors/design-patterns.md

```markdown
# Design Patterns

> Source: `src/content/docs/actors/design-patterns.mdx`
> Canonical URL: https://rivet.dev/docs/actors/design-patterns
> Description: Common patterns and anti-patterns for building scalable actor systems.

---
## How Actors Scale

Actors are inherently scalable because of how they're designed:

- **Isolated state:** Each actor manages its own private data. No shared state means no conflicts and no locks, so actors run concurrently without coordination.
- **Actor-to-actor communication:** Actors interact through [actions](/docs/actors/actions) and [events](/docs/actors/events), so they don't need to coordinate access to shared data. This makes it easy to distribute them across machines.
- **Small, focused units:** Each actor handles a limited scope (a single user, document, or chat room), so load naturally spreads across many actors rather than concentrating in one place.
- **Horizontal scaling:** Adding more machines automatically distributes actors across them.

These properties form the foundation for the patterns described below.

## Actor Per Entity

The core pattern is creating one actor per entity in your system. Each actor represents a single user, document, chat room, or other distinct object. This keeps actors small, independent, and easy to scale.

**Good examples**

- `User`: Manages user profile, preferences, and authentication
- `Document`: Handles document content, metadata, and versioning
- `ChatRoom`: Manages participants and message history

**Bad examples**

- `Application`: Too broad, handles everything
- `DocumentWordCount`: Too granular, should be part of Document actor

## Coordinator & Data Actors

Actors scale by splitting state into isolated entities. However, it's common to need to track and coordinate actors in a central place. This is where coordinator actors come in.

**Data actors** handle the main logic in your application. Examples: chat rooms, user sessions, game lobbies.

**Coordinator actors** track other actors. Think of them as an index of data actors. Examples: a list of chat rooms, a list of active users, a list of game lobbies.

**Example: Chat Room Coordinator**

### Actor

```ts
import { actor, setup } from "rivetkit";

// Data actor: handles messages and connections
const chatRoom = actor({
  state: { messages: [] as { sender: string; text: string }[] },
  actions: {
    sendMessage: (c, sender: string, text: string) => {
      const message = { sender, text };
      c.state.messages.push(message);
      c.broadcast("newMessage", message);
      return message;
    },
    getHistory: (c) => c.state.messages,
  },
});

// Coordinator: indexes chat rooms
const chatRoomList = actor({
  state: { chatRoomIds: [] as string[] },
  actions: {
    createChatRoom: async (c, name: string) => {
      const client = c.client<typeof registry>();
      // Create the chat room actor and get its ID
      const handle = await client.chatRoom.create([name]);
      const actorId = await handle.resolve();
      // Track it in the list
      c.state.chatRoomIds.push(actorId);
      return actorId;
    },
    listChatRooms: (c) => c.state.chatRoomIds,
  },
});

const registry = setup({
  use: { chatRoom, chatRoomList },
});
```

### Client

```ts
import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

const chatRoom = actor({
  state: { messages: [] as { sender: string; text: string }[] },
  actions: {
    sendMessage: (c, sender: string, text: string) => {
      const message = { sender, text };
      c.state.messages.push(message);
      return message;
    },
    getHistory: (c) => c.state.messages,
  },
});

const chatRoomList = actor({
  state: { chatRoomIds: [] as string[] },
  actions: {
    createChatRoom: async (c, name: string) => "room-id",
    listChatRooms: (c) => c.state.chatRoomIds,
  },
});

const registry = setup({ use: { chatRoom, chatRoomList } });
const client = createClient<typeof registry>("http://localhost:8080");

// Create a new chat room via coordinator
const coordinator = client.chatRoomList.getOrCreate(["main"]);
const actorId = await coordinator.createChatRoom("general");

// Get list of all chat rooms
const chatRoomIds = await coordinator.listChatRooms();

// Connect to a chat room using its ID
const chatRoomHandle = client.chatRoom.getForId(actorId);
await chatRoomHandle.sendMessage("alice", "Hello!");
const history = await chatRoomHandle.getHistory();
```

## Sharding

Sharding splits a single actor's workload across multiple actors based on a key. Use this when one actor can't handle all the load or data for an entity.

**How it works:**
- Partition data using a shard key (user ID, region, time bucket, or random)
- Requests are routed to shards based on the key
- Shards operate independently without coordination

**Example: Sharding by Time**

### Actor

```ts
import { actor, setup } from "rivetkit";

interface Event {
  type: string;
  url: string;
}

const hourlyAnalytics = actor({
  state: { events: [] as Event[] },
  actions: {
    trackEvent: (c, event: Event) => {
      c.state.events.push(event);
    },
    getEvents: (c) => c.state.events,
  },
});

export const registry = setup({
  use: { hourlyAnalytics },
});
```

### Client

```ts
import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

interface Event {
  type: string;
  url: string;
}

const hourlyAnalytics = actor({
  state: { events: [] as Event[] },
  actions: {
    trackEvent: (c, event: Event) => {
      c.state.events.push(event);
    },
  },
});

const registry = setup({ use: { hourlyAnalytics } });
const client = createClient<typeof registry>("http://localhost:8080");

// Shard by hour: hourlyAnalytics:2024-01-15T00, hourlyAnalytics:2024-01-15T01
const shardKey = new Date().toISOString().slice(0, 13); // "2024-01-15T00"
const analytics = client.hourlyAnalytics.getOrCreate([shardKey]);
await analytics.trackEvent({ type: "page_view", url: "/home" });
```

**Example: Random Sharding**

### Actor

```ts
import { actor, setup } from "rivetkit";

const rateLimiter = actor({
  state: { requests: {} as Record<string, number> },
  actions: {
    checkLimit: (c, userId: string, limit: number) => {
      const count = c.state.requests[userId] ?? 0;
      if (count >= limit) return false;
      c.state.requests[userId] = count + 1;
      return true;
    },
  },
});

export const registry = setup({
  use: { rateLimiter },
});
```

### Client

```ts
import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

const rateLimiter = actor({
  state: { requests: {} as Record<string, number> },
  actions: {
    checkLimit: (c, userId: string, limit: number) => {
      const count = c.state.requests[userId] ?? 0;
      if (count >= limit) return false;
      c.state.requests[userId] = count + 1;
      return true;
    },
  },
});

const registry = setup({ use: { rateLimiter } });
const client = createClient<typeof registry>("http://localhost:8080");

// Shard randomly: rateLimiter:shard-0, rateLimiter:shard-1, rateLimiter:shard-2
const shardKey = `shard-${Math.floor(Math.random() * 3)}`;
const limiter = client.rateLimiter.getOrCreate([shardKey]);
const allowed = await limiter.checkLimit("user-123", 100);
```

Choose shard keys that distribute load evenly. Note that cross-shard queries require coordination.

## Fan-In & Fan-Out

Fan-in and fan-out are patterns for distributing work and aggregating results.

**Fan-Out**: One actor spawns work across multiple actors. Use for parallel processing or broadcasting updates.

**Fan-In**: Multiple actors send results to one aggregator. Use for collecting results or reducing data.

**Example: Map-Reduce**

### Actor

```ts
import { actor, setup } from "rivetkit";

interface Task {
  id: string;
  data: string;
}

interface Result {
  taskId: string;
  output: string;
}

// Coordinator fans out tasks, then fans in results
const coordinator = actor({
  state: { results: [] as Result[] },
  actions: {
    // Fan-out: distribute work in parallel
    startJob: async (c, tasks: Task[]) => {
      const client = c.client<typeof registry>();
      await Promise.all(
        tasks.map(task => client.worker.getOrCreate(task.id).process(task))
      );
    },
    // Fan-in: collect results
    reportResult: (c, result: Result) => {
      c.state.results.push(result);
    },
    getResults: (c) => c.state.results,
  },
});

const worker = actor({
  state: {},
  actions: {
    process: async (c, task: Task) => {
      const result = { taskId: task.id, output: `Processed ${task.data}` };
      const client = c.client<typeof registry>();
      await client.coordinator.getOrCreate("main").reportResult(result);
    },
  },
});

export const registry = setup({
  use: { coordinator, worker },
});
```

### Client

```ts
import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

interface Task {
  id: string;
  data: string;
}

interface Result {
  taskId: string;
  output: string;
}

const coordinator = actor({
  state: { results: [] as Result[] },
  actions: {
    startJob: async (c, tasks: Task[]) => {},
    reportResult: (c, result: Result) => { c.state.results.push(result); },
    getResults: (c) => c.state.results,
  },
});

const worker = actor({
  state: {},
  actions: {
    process: async (c, task: Task) => {},
  },
});

const registry = setup({ use: { coordinator, worker } });
const client = createClient<typeof registry>("http://localhost:8080");

const coordinatorHandle = client.coordinator.getOrCreate(["main"]);

// Start a job with multiple tasks
await coordinatorHandle.startJob([
  { id: "task-1", data: "..." },
  { id: "task-2", data: "..." },
  { id: "task-3", data: "..." },
]);

// Results are collected as workers report back
const results = await coordinatorHandle.getResults();
```

## Integrating With External Databases & APIs

Actors can integrate with external resources like databases or external APIs.

### Loading State

Load external data during actor initialization using `createVars`. This keeps your actor's persisted state clean while caching expensive lookups.

Use this when:

- Fetching user profiles, configs, or permissions from a database
- Loading data that changes externally and shouldn't be persisted
- Caching expensive API calls or computations

**Example: Loading User Profile**

### Actor

```ts
import { actor, setup } from "rivetkit";

interface User {
  id: string;
  email: string;
  name: string;
}

// Mock database interface for demonstration
const db = {
  users: {
    findById: async (id: string): Promise<User> => ({ id, email: "[email protected]", name: "User" }),
    update: async (id: string, data: Partial<User>) => {},
  },
};

const userSession = actor({
  state: { requestCount: 0 },

  // createVars runs on every wake (after restarts, crashes, or sleep), so
  // external data stays fresh.
  createVars: async (c): Promise<{ user: User }> => {
    // Load from database on every wake
    const user = await db.users.findById(c.key.join("-"));
    return { user };
  },

  actions: {
    getProfile: (c) => {
      c.state.requestCount++;
      return c.vars.user;
    },
    updateEmail: async (c, email: string) => {
      c.state.requestCount++;
      await db.users.update(c.key.join("-"), { email });
      // Refresh cached data
      c.vars.user = await db.users.findById(c.key.join("-"));
    },
  },
});

const registry = setup({
  use: { userSession },
});
```

### Client

```ts
import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

interface User {
  id: string;
  email: string;
  name: string;
}

const userSession = actor({
  state: { requestCount: 0 },
  createVars: () => ({ user: null as User | null }),
  actions: {
    getProfile: (c) => c.vars.user,
    updateEmail: async (c, email: string) => {},
  },
});

const registry = setup({ use: { userSession } });
const client = createClient<typeof registry>("http://localhost:8080");

const session = client.userSession.getOrCreate(["user-123"]);

// Get profile (loaded from database on actor wake)
const profile = await session.getProfile();

// Update email (writes to database and refreshes cache)
await session.updateEmail("[email protected]");
```

### Syncing State Changes

Use `onStateChange` to automatically sync actor state changes to external resources. This hook is called whenever the actor's state is modified.

Use this when:

- You need to mirror actor state in an external database
- Triggering external side effects when state changes
- Keeping external systems in sync with actor state

**Example: Syncing to Database**

### Actor

```ts
import { actor, setup } from "rivetkit";

// Mock database interface for demonstration
const db = {
  users: {
    insert: async (data: { id: string; email: string; createdAt: number }) => {},
    update: async (id: string, data: { email: string; lastActive: number }) => {},
  },
};

const userActor = actor({
  state: {
    email: "",
    lastActive: 0,
  },

  onCreate: async (c, input: { email: string }) => {
    // Insert into database on actor creation
    await db.users.insert({
      id: c.key.join("-"),
      email: input.email,
      createdAt: Date.now(),
    });
  },

  onStateChange: async (c, newState) => {
    // Sync any state changes to database
    await db.users.update(c.key.join("-"), {
      email: newState.email,
      lastActive: newState.lastActive,
    });
  },

  actions: {
    updateEmail: (c, email: string) => {
      c.state.email = email;
      c.state.lastActive = Date.now();
    },
    getUser: (c) => ({
      email: c.state.email,
      lastActive: c.state.lastActive,
    }),
  },
});

const registry = setup({
  use: { userActor },
});
```

### Client

```ts
import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

const userActor = actor({
  state: { email: "", lastActive: 0 },
  actions: {
    updateEmail: (c, email: string) => {
      c.state.email = email;
      c.state.lastActive = Date.now();
    },
    getUser: (c) => ({
      email: c.state.email,
      lastActive: c.state.lastActive,
    }),
  },
});

const registry = setup({ use: { userActor } });
const client = createClient<typeof registry>("http://localhost:8080");

const user = await client.userActor.create(["user-123"], {
  input: { email: "[email protected]" },
});

// Updates state and triggers onStateChange
await user.updateEmail("[email protected]");

const userData = await user.getUser();
```

`onStateChange` is called after every state modification, ensuring external resources stay in sync.

## Anti-Patterns

### "God" Actor

Avoid creating a single actor that handles everything. This defeats the purpose of the actor model and creates a bottleneck.

**Problem:**
```ts
import { actor } from "rivetkit";

// Bad: one actor doing everything
const app = actor({
  state: { users: {}, orders: {}, inventory: {}, analytics: {} },
  actions: {
    createUser: (c, user) => { /* ... */ },
    processOrder: (c, order) => { /* ... */ },
    updateInventory: (c, item) => { /* ... */ },
    trackEvent: (c, event) => { /* ... */ },
  },
});
```

**Solution:** Split into focused actors per entity (User, Order, Inventory, Analytics).

### Actor-Per-Request

Actors are designed to maintain state across multiple requests. Creating a new actor for each request wastes resources and loses the benefits of persistent state.

**Problem:**
```ts
import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";
import { Hono } from "hono";

const processor = actor({
  state: {},
  actions: {
    process: (c, body: unknown) => ({ processed: true }),
    destroy: (c) => {},
  },
});

const registry = setup({ use: { processor } });
const client = createClient<typeof registry>("http://localhost:8080");
const app = new Hono();

// Bad: creating an actor for each API request
app.post("/process", async (c) => {
  const actorHandle = client.processor.getOrCreate([crypto.randomUUID()]);
  const result = await actorHandle.process(await c.req.json());
  await actorHandle.destroy();
  return c.json(result);
});
```

**Solution:** Use actors for entities that persist (users, sessions, documents), not for one-off operations. For stateless request handling, use regular functions.

## API Reference

- [`ActorDefinition`](/typedoc/interfaces/rivetkit.mod.ActorDefinition.html) - Interface for pattern examples
- [`ActorContext`](/typedoc/interfaces/rivetkit.mod.ActorContext.html) - Context usage patterns
- [`ActionContext`](/typedoc/interfaces/rivetkit.mod.ActionContext.html) - Action patterns

_Source doc path: /docs/actors/design-patterns_

```

### reference/actors/destroy.md

```markdown
# Destroying Actors

> Source: `src/content/docs/actors/destroy.mdx`
> Canonical URL: https://rivet.dev/docs/actors/destroy
> Description: Actors can be permanently destroyed. Common use cases include:

---
- User account deletion
- Ending a user session
- Closing a room or game
- Cleaning up temporary resources
- GDPR/compliance data removal

Actors sleep when idle, so destruction is only needed to permanently remove data — not to save compute.

## Destroying An Actor

### Destroy via Action

To destroy an actor, use `c.destroy()` like this:

```typescript
import { actor } from "rivetkit";

interface UserInput {
  email: string;
  name: string;
}

const userActor = actor({
  createState: (c, input: UserInput) => ({
    email: input.email,
    name: input.name,
  }),
  actions: {
    deleteAccount: (c) => {
      c.destroy();
    },
  },
});
```

### Destroy via HTTP

Send a DELETE request to destroy an actor. This requires an admin token for authentication.

```typescript
const actorId = "your-actor-id";
const namespace = "default";
const token = "your-admin-token";

await fetch(`https://api.rivet.dev/actors/${actorId}?namespace=${namespace}`, {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${token}`,
  },
});
```

```bash
curl -X DELETE "https://api.rivet.dev/actors/{actorId}?namespace={namespace}" \
  -H "Authorization: Bearer {token}"
```

	Creating admin tokens is currently not supported on Rivet Cloud. See the [tracking issue](https://github.com/rivet-dev/rivet/issues/3530).

### Destroy via Dashboard

To destroy an actor via the dashboard, navigate to the actor and press the red "X" in the top right.

## Lifecycle Hook

Once destroyed, the `onDestroy` hook will be called. This can be used to clean up resources related to the actor. For example:

```typescript
import { actor } from "rivetkit";

interface UserState {
  email: string;
  name: string;
}

// Example email service interface
const emailService = {
  send: async (options: { from: string; to: string; subject: string; text: string }) => {},
};

const userActor = actor({
  state: { email: "", name: "" } as UserState,
  onDestroy: async (c) => {
    await emailService.send({
      from: "[email protected]",
      to: c.state.email,
      subject: "Account Deleted",
      text: `Goodbye ${c.state.name}, your account has been deleted.`,
    });
  },
  actions: {
    deleteAccount: (c) => {
      c.destroy();
    },
  },
});
```

## Accessing Actor After Destroy

Once an actor is destroyed, any subsequent requests to it will return an `actor_not_found` error. The actor's state is permanently deleted.

## API Reference

- [`ActorHandle`](/typedoc/types/rivetkit.client_mod.ActorHandle.html) - Has destroy methods
- [`ActorContext`](/typedoc/interfaces/rivetkit.mod.ActorContext.html) - Context during destruction

_Source doc path: /docs/actors/destroy_

```

### reference/actors/ephemeral-variables.md

```markdown
# Ephemeral Variables

> Source: `src/content/docs/actors/ephemeral-variables.mdx`
> Canonical URL: https://rivet.dev/docs/actors/ephemeral-variables
> Description: In addition to persisted state, Rivet provides a way to store ephemeral data that is not saved to permanent storage using `vars`. This is useful for temporary data that only needs to exist while the actor is running or data that cannot be serialized.

---
`vars` is designed to complement `state`, not replace it. Most actors should use both: `state` for critical business data and `vars` for ephemeral or non-serializable data.

## Initializing Variables

There are two ways to define an actor's initial vars:

### Static Initial Variables

Define an actor vars as a constant value:

```typescript
import { actor } from "rivetkit";

// Mock event emitter for demonstration
interface EventEmitter {
  on: (event: string, callback: (data: unknown) => void) => void;
  emit: (event: string, data: unknown) => void;
}

function createEventEmitter(): EventEmitter {
  const listeners: Record<string, ((data: unknown) => void)[]> = {};
  return {
    on: (event, callback) => {
      listeners[event] = listeners[event] || [];
      listeners[event].push(callback);
    },
    emit: (event, data) => {
      listeners[event]?.forEach(cb => cb(data));
    }
  };
}

// Define vars as a constant
const counter = actor({
  state: { count: 0 },

  // Define ephemeral variables
  vars: {
    lastAccessTime: 0,
    emitter: createEventEmitter()
  },

  actions: {
    increment: (c) => ++c.state.count
  }
});
```

This value will be cloned for every new actor using `structuredClone`.

### Dynamic Initial Variables

Create actor state dynamically on each actors' start:

```typescript
import { actor } from "rivetkit";

// Mock event emitter for demonstration
interface EventEmitter {
  on: (event: string, callback: (data: unknown) => void) => void;
  emit: (event: string, data: unknown) => void;
}

function createEventEmitter(): EventEmitter {
  const listeners: Record<string, ((data: unknown) => void)[]> = {};
  return {
    on: (event, callback) => {
      listeners[event] = listeners[event] || [];
      listeners[event].push(callback);
    },
    emit: (event, data) => {
      listeners[event]?.forEach(cb => cb(data));
    }
  };
}

// Define vars with initialization logic
const counter = actor({
  state: { count: 0 },

  // Define vars using a creation function
  createVars: () => {
    return {
      lastAccessTime: Date.now(),
      emitter: createEventEmitter()
    };
  },

  actions: {
    increment: (c) => ++c.state.count
  }
});
```

If accepting arguments to `createVars`, you **must** define the types: `createVars(c: CreateVarsContext, driver: any)`

Otherwise, the return type will not be inferred and `c.vars` will be of type `unknown`.

## Using Variables

Vars can be accessed and modified through the context object with `c.vars`:

```typescript
import { actor } from "rivetkit";

// Mock event emitter for demonstration
interface EventEmitter {
  on: (event: string, callback: (data: number) => void) => void;
  emit: (event: string, data: number) => void;
}

function createEventEmitter(): EventEmitter {
  const listeners: Record<string, ((data: number) => void)[]> = {};
  return {
    on: (event, callback) => {
      listeners[event] = listeners[event] || [];
      listeners[event].push(callback);
    },
    emit: (event, data) => {
      listeners[event]?.forEach(cb => cb(data));
    }
  };
}

const counter = actor({
  // Persistent state - saved to storage
  state: { count: 0 },

  // Create ephemeral objects that won't be serialized
  createVars: () => {
    // Create an event emitter (can't be serialized)
    const emitter = createEventEmitter();

    // Set up event listener directly in createVars
    emitter.on('count-changed', (newCount) => {
      console.log(`Count changed to: ${newCount}`);
    });

    return { emitter };
  },

  actions: {
    increment: (c) => {
      // Update persistent state
      c.state.count += 1;

      // Use non-serializable emitter
      c.vars.emitter.emit('count-changed', c.state.count);

      return c.state.count;
    }
  }
});
```

## When to Use `vars` vs `state`

In practice, most actors will use both: `state` for critical business data and `vars` for ephemeral or non-serializable data.

Use `vars` when:

- You need to store temporary data that doesn't need to survive restarts
- You need to maintain runtime-only references that can't be serialized (database connections, event emitters, class instances, etc.)

Use `state` when:

- The data must be preserved across actor sleeps, restarts, updates, or crashes
- The information is essential to the actor's core functionality and business logic

_Source doc path: /docs/actors/ephemeral-variables_

```

### reference/actors/errors.md

```markdown
# Errors

> Source: `src/content/docs/actors/errors.mdx`
> Canonical URL: https://rivet.dev/docs/actors/errors
> Description: Rivet provides robust error handling with security built in by default. Errors are handled differently based on whether they should be exposed to clients or kept private.

---
There are two types of errors:

- **UserError**: Thrown from actors and safely returned to clients with full details
- **Internal errors**: All other errors that are converted to a generic error message for security

## Throwing and Catching Errors

`UserError` lets you throw custom errors that will be safely returned to the client.

Throw a `UserError` with just a message:

### Actor

```typescript
import { actor, UserError } from "rivetkit";

const user = actor({
  state: { username: "" },
  actions: {
    updateUsername: (c, username: string) => {
      // Validate username
      if (username.length > 32) {
        throw new UserError("Username is too long");
      }

      // Update username
      c.state.username = username;
    }
  }
});
```

### Client (Connection)

```typescript
import { actor, setup } from "rivetkit";
import { createClient, ActorError } from "rivetkit/client";

const user = actor({
  state: { username: "" },
  actions: {
    updateUsername: (c, username: string) => {
      if (username.length > 32) throw new Error("Username is too long");
      c.state.username = username;
    }
  }
});

const registry = setup({ use: { user } });
const client = createClient<typeof registry>("http://localhost:8080");
const conn = client.user.getOrCreate([]).connect();

try {
  await conn.updateUsername("extremely_long_username_that_exceeds_the_limit");
} catch (error) {
  if (error instanceof ActorError) {
    console.log(error.message); // "Username is too long"
  }
}
```

### Client (Stateless)

```typescript
import { actor, setup } from "rivetkit";
import { createClient, ActorError } from "rivetkit/client";

const user = actor({
  state: { username: "" },
  actions: {
    updateUsername: (c, username: string) => {
      if (username.length > 32) throw new Error("Username is too long");
      c.state.username = username;
    }
  }
});

const registry = setup({ use: { user } });
const client = createClient<typeof registry>("http://localhost:8080");
const userActor = client.user.getOrCreate([]);

try {
  await userActor.updateUsername("extremely_long_username_that_exceeds_the_limit");
} catch (error) {
  if (error instanceof ActorError) {
    console.log(error.message); // "Username is too long"
  }
}
```

## Error Codes

Use error codes for explicit error matching in try-catch blocks:

### Actor

```typescript
import { actor, UserError } from "rivetkit";

const user = actor({
  state: { username: "" },
  actions: {
    updateUsername: (c, username: string) => {
      if (username.length < 3) {
        throw new UserError("Username is too short", {
          code: "username_too_short"
        });
      }

      if (username.length > 32) {
        throw new UserError("Username is too long", {
          code: "username_too_long"
        });
      }

      // Update username
      c.state.username = username;
    }
  }
});
```

### Client (Connection)

```typescript
import { actor, setup } from "rivetkit";
import { createClient, ActorError } from "rivetkit/client";

const user = actor({
  state: { username: "" },
  actions: {
    updateUsername: (c, username: string) => { c.state.username = username; }
  }
});

const registry = setup({ use: { user } });
const client = createClient<typeof registry>("http://localhost:8080");
const conn = client.user.getOrCreate([]).connect();

try {
  await conn.updateUsername("ab");
} catch (error) {
  if (error instanceof ActorError) {
    if (error.code === "username_too_short") {
      console.log("Please choose a longer username");
    } else if (error.code === "username_too_long") {
      console.log("Please choose a shorter username");
    }
  }
}
```

### Client (Stateless)

```typescript
import { actor, setup } from "rivetkit";
import { createClient, ActorError } from "rivetkit/client";

const user = actor({
  state: { username: "" },
  actions: {
    updateUsername: (c, username: string) => { c.state.username = username; }
  }
});

const registry = setup({ use: { user } });
const client = createClient<typeof registry>("http://localhost:8080");
const userActor = client.user.getOrCreate([]);

try {
  await userActor.updateUsername("ab");
} catch (error) {
  if (error instanceof ActorError) {
    if (error.code === "username_too_short") {
      console.log("Please choose a longer username");
    } else if (error.code === "username_too_long") {
      console.log("Please choose a shorter username");
    }
  }
}
```

## Errors With Metadata

Include metadata to provide additional context for rich error handling:

### Actor

```typescript
import { actor, UserError } from "rivetkit";

const api = actor({
  state: { requestCount: 0, lastReset: Date.now() },
  actions: {
    makeRequest: (c) => {
      c.state.requestCount++;

      const limit = 100;
      if (c.state.requestCount > limit) {
        const resetAt = c.state.lastReset + 60_000; // Reset after 1 minute

        throw new UserError("Rate limit exceeded", {
          code: "rate_limited",
          metadata: {
            limit: limit,
            resetAt: resetAt,
            retryAfter: Math.ceil((resetAt - Date.now()) / 1000)
          }
        });
      }

      // Rest of request logic...
    }
  }
});
```

### Client (Connection)

```typescript
import { actor, setup } from "rivetkit";
import { createClient, ActorError } from "rivetkit/client";

const api = actor({
  state: { requestCount: 0 },
  actions: { makeRequest: (c) => {} }
});

const registry = setup({ use: { api } });
const client = createClient<typeof registry>("http://localhost:8080");
const conn = client.api.getOrCreate([]).connect();

try {
  await conn.makeRequest();
} catch (error) {
  if (error instanceof ActorError) {
    console.log(error.message); // "Rate limit exceeded"
    console.log(error.code); // "rate_limited"
    console.log(error.metadata); // { limit: 100, resetAt: 1234567890, retryAfter: 45 }

    if (error.code === "rate_limited") {
      const metadata = error.metadata as { retryAfter: number };
      console.log(`Rate limit hit. Try again in ${metadata.retryAfter} seconds`);
    }
  }
}
```

### Client (Stateless)

```typescript
import { actor, setup } from "rivetkit";
import { createClient, ActorError } from "rivetkit/client";

const api = actor({
  state: { requestCount: 0 },
  actions: { makeRequest: (c) => {} }
});

const registry = setup({ use: { api } });
const client = createClient<typeof registry>("http://localhost:8080");
const apiActor = client.api.getOrCreate([]);

try {
  await apiActor.makeRequest();
} catch (error) {
  if (error instanceof ActorError) {
    console.log(error.message); // "Rate limit exceeded"
    console.log(error.code); // "rate_limited"
    console.log(error.metadata); // { limit: 100, resetAt: 1234567890, retryAfter: 45 }

    if (error.code === "rate_limited") {
      const metadata = error.metadata as { retryAfter: number };
      console.log(`Rate limit hit. Try again in ${metadata.retryAfter} seconds`);
    }
  }
}
```

## Internal Errors

All errors that are not UserError instances are automatically converted to a generic "internal error" response. This prevents accidentally leaking sensitive information like stack traces, database details, or internal system information.

### Actor

```typescript
import { actor } from "rivetkit";

const payment = actor({
  state: { transactions: [] },
  actions: {
    processPayment: async (c, amount: number) => {
      // This will throw a regular Error (not UserError)
      const result = await fetch("https://payment-api.example.com/charge", {
        method: "POST",
        body: JSON.stringify({ amount })
      });

      if (!result.ok) {
        // This internal error will be hidden from the client
        throw new Error(`Payment API returned ${result.status}: ${await result.text()}`);
      }

      // Rest of payment logic...
    }
  }
});
```

### Client (Connection)

```typescript
import { actor, setup } from "rivetkit";
import { createClient, ActorError } from "rivetkit/client";

interface Transaction {
  amount: number;
  status: string;
}

const payment = actor({
  state: { transactions: [] as Transaction[] },
  actions: { processPayment: async (c, amount: number) => {} }
});

const registry = setup({ use: { payment } });
const client = createClient<typeof registry>("http://localhost:8080");
const conn = client.payment.getOrCreate([]).connect();

try {
  await conn.processPayment(100);
} catch (error) {
  if (error instanceof ActorError) {
    console.log(error.code); // "internal_error"
    console.log(error.message); // "Internal error. Read the server logs for more details."

    // Original error details are NOT exposed to the client
    // Check your server logs to see the actual error message
  }
}
```

### Client (Stateless)

```typescript
import { actor, setup } from "rivetkit";
import { createClient, ActorError } from "rivetkit/client";

interface Transaction {
  amount: number;
  status: string;
}

const payment = actor({
  state: { transactions: [] as Transaction[] },
  actions: { processPayment: async (c, amount: number) => {} }
});

const registry = setup({ use: { payment } });
const client = createClient<typeof registry>("http://localhost:8080");
const paymentActor = client.payment.getOrCreate([]);

try {
  await paymentActor.processPayment(100);
} catch (error) {
  if (error instanceof ActorError) {
    console.log(error.code); // "internal_error"
    console.log(error.message); // "Internal error. Read the server logs for more details."

    // Original error details are NOT exposed to the client
    // Check your server logs to see the actual error message
  }
}
```

### Server-Side Logging

**All internal errors are logged server-side with full details.** When an internal error occurs, the complete error message, stack trace, and context are written to your server logs. This is where you should look first when debugging internal errors in production.

The client receives only a generic "Internal error" message for security, but you can find the full error details in your server logs including:

- Complete error message
- Stack trace
- Request context (actor ID, action name, connection ID, etc.)
- Timestamp

**Always check your server logs to see the actual error details when debugging internal errors.**

### Exposing Errors to Clients (Development Only)

**Warning:** Only enable error exposure in development environments. In production, this will leak sensitive internal details to clients.

For faster debugging during development, you can automatically expose internal error details to clients. This is enabled when:

- `NODE_ENV=development` - Automatically enabled in development mode
- `RIVET_EXPOSE_ERRORS=1` - Explicitly enable error exposure

With error exposure enabled, clients will see the full error message instead of the generic "Internal error" response:

```typescript
import { actor, setup } from "rivetkit";
import { createClient, ActorError } from "rivetkit/client";

const payment = actor({
  state: {},
  actions: { processPayment: async (c, amount: number) => {} }
});

const registry = setup({ use: { payment } });
const client = createClient<typeof registry>("http://localhost:8080");
const paymentActor = client.payment.getOrCreate([]);

// With NODE_ENV=development or RIVET_EXPOSE_ERRORS=1
try {
  await paymentActor.processPayment(100);
} catch (error) {
  if (error instanceof ActorError) {
    console.log(error.message);
    // "Payment API returned 402: Insufficient funds"
    // Instead of: "Internal error. Read the server logs for more details."
  }
}
```

## API Reference

- [`UserError`](/typedoc/classes/rivetkit.actor_errors.UserError.html) - User-facing error class
- [`ActorError`](/typedoc/classes/rivetkit.client_mod.ActorError.html) - Errors received by the client

_Source doc path: /docs/actors/errors_

```

### reference/actors/events.md

```markdown
# Events

> Source: `src/content/docs/actors/events.mdx`
> Canonical URL: https://rivet.dev/docs/actors/events
> Description: Events enable real-time communication from actors to clients. While clients use actions to send data to actors, events allow actors to push updates to connected clients instantly.

---
Events can be sent to clients connected using `.connect()`. They have no effect on [low-level WebSocket connections](/docs/actors/websocket-handler).

## Publishing Events from Actors

### Broadcasting to All Clients

Use `c.broadcast(eventName, data)` to send events to all connected clients:

```typescript
import { actor } from "rivetkit";

const chatRoom = actor({
  state: { 
    messages: [] as Array<{id: string, userId: string, text: string, timestamp: number}>
  },
  
  actions: {
    sendMessage: (c, userId: string, text: string) => {
      const message = {
        id: crypto.randomUUID(),
        userId,
        text,
        timestamp: Date.now()
      };
      
      c.state.messages.push(message);
      
      // Broadcast to all connected clients
      c.broadcast('messageReceived', message);
      
      return message;
    },
  }
});
```

### Sending to Specific Connections

Send events to individual connections using `conn.send(eventName, data)`:

```typescript
import { actor } from "rivetkit";

interface ConnState {
  playerId: string;
  role: string;
}

const gameRoom = actor({
  state: {
    players: {} as Record<string, {health: number, position: {x: number, y: number}}>
  },
  connState: { playerId: "", role: "player" } as ConnState,

  createConnState: (c, params: { playerId: string, role?: string }) => ({
    playerId: params.playerId,
    role: params.role || "player"
  }),

  actions: {
    sendPrivateMessage: (c, targetPlayerId: string, message: string) => {
      // Find the target player's connection
      let targetConn = null;
      for (const conn of c.conns.values()) {
        if (conn.state.playerId === targetPlayerId) {
          targetConn = conn;
          break;
        }
      }

      if (targetConn) {
        targetConn.send('privateMessage', {
          from: c.conn?.state.playerId,
          message,
          timestamp: Date.now()
        });
      } else {
        throw new Error("Player not found or not connected");
      }
    }
  }
});
```

Send events to all connections except the sender:

```typescript
import { actor } from "rivetkit";

interface ConnState {
  playerId: string;
  role: string;
}

const gameRoom = actor({
  state: {
    players: {} as Record<string, {health: number, position: {x: number, y: number}}>
  },
  connState: { playerId: "", role: "player" } as ConnState,

  createConnState: (c, params: { playerId: string, role?: string }) => ({
    playerId: params.playerId,
    role: params.role || "player"
  }),

  actions: {
    updatePlayerPosition: (c, position: {x: number, y: number}) => {
      const playerId = c.conn?.state.playerId;
      if (!playerId) return;

      if (c.state.players[playerId]) {
        c.state.players[playerId].position = position;

        // Send position update to all OTHER players
        for (const conn of c.conns.values()) {
          if (conn.state.playerId !== playerId) {
            conn.send('playerMoved', { playerId, position });
          }
        }
      }
    }
  }
});
```

## Subscribing to Events from Clients

Clients must establish a connection to receive events from actors. Use `.connect()` to create a persistent connection, then listen for events.

### Basic Event Subscription

Use `connection.on(eventName, callback)` to listen for events:

```typescript {{"title":"TypeScript"}}
import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

// Define the actor
const chatRoom = actor({
  state: { messages: [] as Array<{id: string, userId: string, text: string}> },
  actions: {
    sendMessage: (c, userId: string, text: string) => {
      const message = { id: crypto.randomUUID(), userId, text };
      c.state.messages.push(message);
      c.broadcast('messageReceived', message);
      return message;
    }
  }
});

const registry = setup({ use: { chatRoom } });
const client = createClient<typeof registry>("http://localhost:8080");

// Helper function for demonstration
function displayMessage(message: { userId: string; text: string }) {
  console.log("Display:", message);
}

// Get actor handle and establish connection
const chatRoomHandle = client.chatRoom.getOrCreate(["general"]);
const connection = chatRoomHandle.connect();

// Listen for events
connection.on('messageReceived', (message: { userId: string; text: string }) => {
  console.log(`${message.userId}: ${message.text}`);
  displayMessage(message);
});

// Call actions through the connection
await connection.sendMessage("user-123", "Hello everyone!");
```

```tsx React @nocheck
import { useState } from "react";
import { useActor } from "./rivetkit";

function ChatRoom() {
  const [messages, setMessages] = useState<Array<{id: string, userId: string, text: string}>>([]);

  const chatRoom = useActor({
    name: "chatRoom",
    key: ["general"]
  });

  // Listen for events
  chatRoom.useEvent("messageReceived", (message) => {
    setMessages(prev => [...prev, message]);
  });

  // ...rest of component...
}
```

### One-time Event Listeners

Use `connection.once(eventName, callback)` for events that should only trigger once:

```typescript {{"title":"TypeScript"}}
import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

const gameRoom = actor({
  state: { started: false },
  actions: {
    startGame: (c) => {
      c.state.started = true;
      c.broadcast('gameStarted', {});
    }
  }
});

const registry = setup({ use: { gameRoom } });
const client = createClient<typeof registry>("http://localhost:8080");

function showGameInterface() {
  console.log("Showing game interface");
}

const gameRoomHandle = client.gameRoom.getOrCreate(["room-456"]);
const connection = gameRoomHandle.connect();

// Listen for game start (only once)
connection.once('gameStarted', () => {
  console.log('Game has started!');
  showGameInterface();
});
```

```tsx React @nocheck
import { useState, useEffect } from "react";
import { useActor } from "./rivetkit";

function GameLobby() {
  const [gameStarted, setGameStarted] = useState(false);

  const gameRoom = useActor({
    name: "gameRoom",
    key: ["room-456"],
    params: {
      playerId: "player-789",
      role: "player"
    }
  });

  // Listen for game start (only once)
  useEffect(() => {
    if (!gameRoom.connection) return;

    const handleGameStart = () => {
      console.log('Game has started!');
      setGameStarted(true);
    };

    gameRoom.connection.once('gameStarted', handleGameStart);
  }, [gameRoom.connection]);

  // ...rest of component...
}
```

### Removing Event Listeners

Use the callback returned from `.on()` to remove event listeners:

```typescript {{"title":"TypeScript"}}
import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

const chatRoom = actor({
  state: { messages: [] as string[] },
  actions: {
    sendMessage: (c, text: string) => {
      c.state.messages.push(text);
      c.broadcast('messageReceived', { text });
    }
  }
});

const registry = setup({ use: { chatRoom } });
const client = createClient<typeof registry>("http://localhost:8080");
const connection = client.chatRoom.getOrCreate(["general"]).connect();

// Add listener
const unsubscribe = connection.on('messageReceived', (message: { text: string }) => {
  console.log("Received:", message);
});

// Remove listener
unsubscribe();
```

```tsx React @nocheck
import { useState, useEffect } from "react";
import { useActor } from "./rivetkit";

function ConditionalListener() {
  const [isListening, setIsListening] = useState(false);
  const [messages, setMessages] = useState<string[]>([]);

  const chatRoom = useActor({
    name: "chatRoom",
    key: ["general"]
  });

  useEffect(() => {
    if (!chatRoom.connection || !isListening) return;

    // Add listener
    const unsubscribe = chatRoom.connection.on('messageReceived', (message) => {
      setMessages(prev => [...prev, `${message.userId}: ${message.text}`]);
    });

    // Cleanup - remove listener when component unmounts or listening stops
    return () => {
      unsubscribe();
    };
  }, [chatRoom.connection, isListening]);

  // ...rest of component...
}
```

## More About Connections

For more details on actor connections, including connection lifecycle, authentication, and advanced connection patterns, see the [Connections documentation](/docs/actors/connections).

## API Reference

- [`RivetEvent`](/typedoc/interfaces/rivetkit.mod.RivetEvent.html) - Base event interface
- [`RivetMessageEvent`](/typedoc/interfaces/rivetkit.mod.RivetMessageEvent.html) - Message event type
- [`RivetCloseEvent`](/typedoc/interfaces/rivetkit.mod.RivetCloseEvent.html) - Close event type
- [`UniversalEvent`](/typedoc/interfaces/rivetkit.mod.UniversalEvent.html) - Universal event type
- [`UniversalMessageEvent`](/typedoc/interfaces/rivetkit.mod.UniversalMessageEvent.html) - Universal message event
- [`UniversalErrorEvent`](/typedoc/interfaces/rivetkit.mod.UniversalErrorEvent.html) - Universal error event
- [`EventUnsubscribe`](/typedoc/types/rivetkit.client_mod.EventUnsubscribe.html) - Unsubscribe function type

_Source doc path: /docs/actors/events_

```

### reference/actors/external-sql.md

```markdown
# External SQL Database

> Source: `src/content/docs/actors/external-sql.mdx`
> Canonical URL: https://rivet.dev/docs/actors/external-sql
> Description: While actors can serve as a complete database solution, they can also complement your existing databases. For example, you might use actors to handle frequently-changing data that needs real-time access, while keeping less frequently accessed data in your traditional database.

---
Actors can be used with common SQL databases, such as PostgreSQL and MySQL.

## Libraries

To facilitate interaction with SQL databases, you can use either ORM libraries or raw SQL drivers. Each has its own use cases and benefits:

-   **ORM Libraries**: Type-safe and easy way to interact with your database

    -   [Drizzle](https://orm.drizzle.team/)
    -   [Prisma](https://www.prisma.io/)

-   **Raw SQL Drivers**: Direct access to the database for more flexibility

    -   [PostgreSQL](https://node-postgres.com/)
    -   [MySQL](https://github.com/mysqljs/mysql)

## Hosting Providers

There are several options for places to host your SQL database:

-   [Supabase](https://supabase.com/)
-   [Neon](https://neon.tech/)
-   [PlanetScale](https://planetscale.com/)
-   [AWS RDS](https://aws.amazon.com/rds/)
-   [Google Cloud SQL](https://cloud.google.com/sql)

## Examples

### Basic PostgreSQL Connection

Here's a basic example of a user actor that creates a database record on start and tracks request counts:

```typescript registry.ts @nocheck
import { actor, setup } from "rivetkit";
import { Pool } from "pg";

interface ActorInput {
  username: string;
  email: string;
}

// Create a database connection pool
const pool = new Pool({
  user: "your_db_user",
  host: "localhost",
  database: "your_db_name",
  password: "your_db_password",
  port: 5432,
});

// Create the user actor
export const userActor = actor({
  createState: (c, input: ActorInput) => ({
    requestCount: 0,
    username: input.username,
    email: input.email,
    lastActive: Date.now()
  }),

  // Insert user into database when actor creates
  onCreate: async (c) => {
    await pool.query(
      "INSERT INTO users (username, email, created_at) VALUES ($1, $2, $3)",
      [c.state.username, c.state.email, c.state.lastActive]
    );
  },

  // Sync state changes to database
  onStateChange: async (c, newState) => {
    await pool.query(
      "UPDATE users SET email = $1, last_active = $2 WHERE username = $3",
      [newState.email, newState.lastActive, newState.username]
    );
  },

  actions: {
    // Update user information, this will trigger onStateChange
    updateUser: async (c, email: string) => {
      c.state.requestCount++;
      c.state.email = email;
      c.state.lastActive = Date.now();

      return { requestCount: c.state.requestCount };
    },

    // Get user data
    getUser: async (c) => {
      c.state.requestCount++;
      c.state.lastActive = Date.now();

      return {
        username: c.key[0],
        email: c.state.email,
        requestCount: c.state.requestCount,
        lastActive: c.state.lastActive
      };
    }
  }
});

export const registry = setup({
  use: { userActor },
});
```

```typescript client.ts @nocheck
import { createClient } from "rivetkit/client";
import type { registry } from "./registry";

const client = createClient<typeof registry>("http://localhost:8080");

// Create user
const alice = await client.userActor.create("alice", {
  input: {
    username: "alice",
    email: "[email protected]"
  }
});

alice.updateUser("[email protected]");

const userData = await alice.getUser();
console.log("User data:", userData);

// Create another user
const bob = await client.userActor.create("bob", {
  input: {
    email: "[email protected]"
  }
});
const bobData = await bob.getUser();
```

### Using Drizzle ORM

Here's the same user actor pattern using Drizzle ORM for more type-safe database operations:

```typescript registry.ts @nocheck
import { actor, setup } from "rivetkit";
import { drizzle } from "drizzle-orm/node-postgres";
import { pgTable, text, timestamp } from "drizzle-orm/pg-core";
import { eq } from "drizzle-orm";
import { Pool } from "pg";

interface ActorInput {
  username: string;
  email: string;
}

// Define your schema
const users = pgTable("users", {
  username: text("username").primaryKey(),
  email: text("email"),
  createdAt: timestamp("created_at").defaultNow(),
  lastActive: timestamp("last_active").defaultNow()
});

// Create a database connection
const pool = new Pool({
  connectionString: process.env.DATABASE_URL
});

// Initialize Drizzle with the pool
const db = drizzle(pool);

// Create the user actor
export const userActor = actor({
  createState: (c, input: ActorInput) => ({
    requestCount: 0,
    username: input.username,
    email: input.email,
    lastActive: Date.now()
  }),

  // Insert user into database when actor creates
  onCreate: async (c) => {
    await db.insert(users).values({
      username: c.state.username,
      email: c.state.email,
      createdAt: new Date(c.state.lastActive)
    });
  },

  // Sync state changes to database
  onStateChange: async (c, newState) => {
    await db.update(users)
      .set({
        email: newState.email,
        lastActive: new Date(newState.lastActive)
      })
      .where(eq(users.username, newState.username));
  },

  actions: {
    // Update user information, this will trigger onStateChange
    updateUser: async (c, email: string) => {
      c.state.requestCount++;
      c.state.email = email;
      c.state.lastActive = Date.now();

      return { requestCount: c.state.requestCount };
    },

    // Get user data
    getUser: async (c) => {
      c.state.requestCount++;
      c.state.lastActive = Date.now();

      return {
        username: c.state.username,
        email: c.state.email,
        requestCount: c.state.requestCount,
        lastActive: c.state.lastActive
      };
    }
  }
});

export const registry = setup({
  use: { userActor },
});
```

```typescript client.ts @nocheck
import { createClient } from "rivetkit/client";
import type { registry } from "./registry";

const client = createClient<typeof registry>("http://localhost:8080");

// Create user
const alice = await client.userActor.create("alice", {
  input: {
    username: "alice",
    email: "[email protected]"
  }
});

alice.updateUser("[email protected]");

const userData = await alice.getUser();
console.log("User data:", userData);

// Create another user
const bob = await client.userActor.create("bob", {
  input: {
    username: "bob",
    email: "[email protected]"
  }
});
const bobData = await bob.getUser();
```

_Source doc path: /docs/actors/external-sql_

```

### reference/actors/fetch-and-websocket-handler.md

```markdown
# Fetch and WebSocket Handler

> Source: `src/content/docs/actors/fetch-and-websocket-handler.mdx`
> Canonical URL: https://rivet.dev/docs/actors/fetch-and-websocket-handler
> Description: These docs have moved to [Low-Level WebSocket Handler](/docs/actors/websocket-handler) and [Low-Level Request Handler](/docs/actors/request-handler).

---


_Source doc path: /docs/actors/fetch-and-websocket-handler_

```

### reference/actors/helper-types.md

```markdown
# Helper Types

> Source: `src/content/docs/actors/helper-types.mdx`
> Canonical URL: https://rivet.dev/docs/actors/helper-types
> Description: This page has moved to [Types](/docs/actors/types).

---


_Source doc path: /docs/actors/helper-types_

```

### reference/actors/input.md

```markdown
# Input Parameters

> Source: `src/content/docs/actors/input.mdx`
> Canonical URL: https://rivet.dev/docs/actors/input
> Description: Pass initialization data to actors when creating instances

---
Actors can receive input parameters when created, allowing for flexible initialization and configuration. Input is passed during actor creation and is available in lifecycle hooks.

## Passing Input to Actors

Input is provided when creating actor instances using the `input` property:

```typescript
import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

interface GameInput {
  gameMode: string;
  maxPlayers: number;
  difficulty?: string;
}

const game = actor({
  state: { gameMode: "", maxPlayers: 0, difficulty: "medium" },
  createState: (c, input: GameInput) => ({
    gameMode: input.gameMode,
    maxPlayers: input.maxPlayers,
    difficulty: input.difficulty ?? "medium",
  }),
  actions: {}
});

const registry = setup({ use: { game } });
const client = createClient<typeof registry>();

// Client side - create with input
const gameHandle = await client.game.create(["game-123"], {
  input: {
    gameMode: "tournament",
    maxPlayers: 8,
    difficulty: "hard",
  }
});

// getOrCreate can also accept input (used only if creating)
const gameHandle2 = client.game.getOrCreate(["game-456"], {
  createWithInput: {
    gameMode: "casual",
    maxPlayers: 4,
  }
});
```

## Accessing Input in Lifecycle Hooks

Input is available in lifecycle hooks via the `opts.input` parameter:

```typescript
import { actor } from "rivetkit";

interface ChatRoomInput {
  roomName: string;
  isPrivate: boolean;
  maxUsers?: number;
}

interface ChatRoomState {
  name: string;
  isPrivate: boolean;
  maxUsers: number;
  users: Record<string, boolean>;
  messages: string[];
}

// Mock function for demonstration
function setupPrivateRoomLogging(roomName: string) {
  console.log(`Setting up logging for private room: ${roomName}`);
}

const chatRoom = actor({
  state: { name: "", isPrivate: false, maxUsers: 50, users: {}, messages: [] } as ChatRoomState,
  createState: (c, input: ChatRoomInput): ChatRoomState => ({
    name: input?.roomName ?? "Unnamed Room",
    isPrivate: input?.isPrivate ?? false,
    maxUsers: input?.maxUsers ?? 50,
    users: {},
    messages: [],
  }),

  onCreate: (c, input: ChatRoomInput) => {
    console.log(`Creating room: ${input.roomName}`);

    // Setup external services based on input
    if (input.isPrivate) {
      setupPrivateRoomLogging(input.roomName);
    }
  },

  actions: {
    // Input remains accessible in actions via initial state
    getRoomInfo: (c) => ({
      name: c.state.name,
      isPrivate: c.state.isPrivate,
      maxUsers: c.state.maxUsers,
      currentUsers: Object.keys(c.state.users).length,
    }),
  },
});
```

## Input Validation

You can validate input parameters in the `createState` or `onCreate` hooks:

```typescript
import { actor } from "rivetkit";
import { z } from "zod";

const GameInputSchema = z.object({
  gameMode: z.enum(["casual", "tournament", "ranked"]),
  maxPlayers: z.number().min(2).max(16),
  difficulty: z.enum(["easy", "medium", "hard"]).optional(),
});

type GameInput = z.infer<typeof GameInputSchema>;

interface GameState {
  gameMode: string;
  maxPlayers: number;
  difficulty: string;
  players: Record<string, boolean>;
  gameState: string;
}

const game = actor({
  state: { gameMode: "", maxPlayers: 0, difficulty: "medium", players: {}, gameState: "waiting" } as GameState,
  createState: (c, inputRaw: GameInput): GameState => {
    // Validate input
    const input = GameInputSchema.parse(inputRaw);

    return {
      gameMode: input.gameMode,
      maxPlayers: input.maxPlayers,
      difficulty: input.difficulty ?? "medium",
      players: {},
      gameState: "waiting",
    };
  },

  actions: {
    // Actions can access the validated input via state
    getGameInfo: (c) => ({
      gameMode: c.state.gameMode,
      maxPlayers: c.state.maxPlayers,
      difficulty: c.state.difficulty,
      currentPlayers: Object.keys(c.state.players).length,
    }),
  },
});
```

## Input vs Connection Parameters

Input parameters are different from connection parameters:

- **Input**:
  - Passed when creating the actor instance
  - Use for actor-wide configuration
  - Available in lifecycle hooks
- **Connection parameters**:
  - Passed when connecting to an existing actor
  - Used for connection-specific configuration
  - Available in connection hooks

```typescript
import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

interface RoomInput { roomName: string; isPrivate: boolean; }

const chatRoom = actor({
  state: { name: "", isPrivate: false },
  createState: (c, input: RoomInput) => ({ name: input.roomName, isPrivate: input.isPrivate }),
  connState: { userId: "", displayName: "" },
  createConnState: (c, params: { userId: string; displayName: string }) => ({
    userId: params.userId,
    displayName: params.displayName,
  }),
  actions: {}
});

const registry = setup({ use: { chatRoom } });
const client = createClient<typeof registry>();

// Actor creation with input
const room = await client.chatRoom.create(["room-123"], {
  input: {
    roomName: "General Discussion",
    isPrivate: false,
  },
});
```

## Input Best Practices

### Use Type Safety

Define input types to ensure type safety:

```typescript
import { actor } from "rivetkit";

interface GameInput {
  gameMode: "casual" | "tournament" | "ranked";
  maxPlayers: number;
  difficulty?: "easy" | "medium" | "hard";
}

interface GameState {
  gameMode: string;
  maxPlayers: number;
  difficulty: string;
}

const game = actor({
  state: { gameMode: "", maxPlayers: 0, difficulty: "medium" } as GameState,
  createState: (c, input: GameInput): GameState => ({
    gameMode: input.gameMode,
    maxPlayers: input.maxPlayers,
    difficulty: input.difficulty ?? "medium",
  }),

  actions: {
    // Actions are now type-safe
  },
});
```

### Store Input in State

If you need to access input data in actions, store it in the actor's state:

```typescript
import { actor } from "rivetkit";

interface GameInput {
  gameMode: string;
  maxPlayers: number;
  difficulty?: string;
}

interface GameConfig {
  gameMode: string;
  maxPlayers: number;
  difficulty: string;
}

interface GameState {
  config: GameConfig;
  players: Record<string, boolean>;
  gameState: string;
}

const game = actor({
  state: {
    config: { gameMode: "", maxPlayers: 0, difficulty: "medium" },
    players: {},
    gameState: "waiting"
  } as GameState,
  createState: (c, input: GameInput): GameState => ({
    // Store input configuration in state
    config: {
      gameMode: input.gameMode,
      maxPlayers: input.maxPlayers,
      difficulty: input?.difficulty ?? "medium",
    },
    // Runtime state
    players: {},
    gameState: "waiting",
  }),

  actions: {
    getConfig: (c) => c.state.config,
    updateDifficulty: (c, difficulty: string) => {
      c.state.config.difficulty = difficulty;
    },
  },
});
```

## API Reference

- [`CreateOptions`](/typedoc/interfaces/rivetkit.client_mod.CreateOptions.html) - Options for creating actors
- [`CreateRequest`](/typedoc/types/rivetkit.client_mod.CreateRequest.html) - Request type for creation
- [`ActorDefinition`](/typedoc/interfaces/rivetkit.mod.ActorDefinition.html) - Interface for defining input types

_Source doc path: /docs/actors/input_

```

### reference/actors/lifecycle.md

```markdown
# Lifecycle

> Source: `src/content/docs/actors/lifecycle.mdx`
> Canonical URL: https://rivet.dev/docs/actors/lifecycle
> Description: Actors follow a well-defined lifecycle with hooks at each stage. Understanding these hooks is essential for proper initialization, state management, and cleanup.

---
## Lifecycle

Actors transition through several states during their lifetime. Each transition triggers specific hooks that let you initialize resources, manage connections, and clean up state.

**On Create** (runs once per actor)

1. `createState`
2. `onCreate`
3. `createVars`
4. `onWake`

**On Destroy**

1. `onDestroy`

**On Wake** (after sleep, restart, or crash)

1. `createVars`
2. `onWake`

**On Sleep** (after idle period)

1. `onSleep`

**On Connect** (per client)

1. `onBeforeConnect`
2. `createConnState`
3. `onConnect`

**On Disconnect** (per client)

1. `onDisconnect`

## Lifecycle Hooks

Actor lifecycle hooks are defined as functions in the actor configuration.

### `state`

The `state` constant defines the initial state of the actor. See [state documentation](/docs/actors/state) for more information.

```typescript
import { actor } from "rivetkit";

const counter = actor({
  state: { count: 0 },
  actions: { /* ... */ }
});
```

### `createState`

[API Reference](/typedoc/interfaces/rivetkit.mod.ActorDefinition.html)

The `createState` function dynamically initializes state based on input. Called only once when the actor is first created. Can be async. See [state documentation](/docs/actors/state) for more information.

```typescript
import { actor } from "rivetkit";

const counter = actor({
  createState: (c, input: { initialCount: number }) => ({
    count: input.initialCount
  }),
  actions: { /* ... */ }
});
```

### `vars`

The `vars` constant defines ephemeral variables for the actor. These variables are not persisted and are useful for storing runtime-only data. The value for `vars` must be clonable via `structuredClone`. See [ephemeral variables documentation](/docs/actors/state#ephemeral-variables-vars) for more information.

```typescript
import { actor } from "rivetkit";

const counter = actor({
  state: { count: 0 },
  vars: { lastAccessTime: 0 },
  actions: { /* ... */ }
});
```

### `createVars`

[API Reference](/typedoc/interfaces/rivetkit.mod.ActorDefinition.html)

The `createVars` function dynamically initializes ephemeral variables. Can be async. Use this when you need to initialize values at runtime. The `driverCtx` parameter provides driver-specific context. See [ephemeral variables documentation](/docs/actors/state#ephemeral-variables-vars) for more information.

```typescript
import { actor } from "rivetkit";

interface CounterVars {
  lastAccessTime: number;
  emitter: EventTarget;
}

const counter = actor({
  state: { count: 0 },
  createVars: (c, driverCtx): CounterVars => ({
    lastAccessTime: Date.now(),
    emitter: new EventTarget()
  }),
  actions: { /* ... */ }
});
```

### `onCreate`

[API Reference](/typedoc/interfaces/rivetkit.mod.ActorDefinition.html)

The `onCreate` hook is called when the actor is first created. Can be async. Use this hook for initialization logic that doesn't affect the initial state.

```typescript
import { actor } from "rivetkit";

const counter = actor({
  state: { count: 0 },

  onCreate: (c, input: { initialCount: number }) => {
    console.log("Actor created with initial count:", input.initialCount);
  },

  actions: { /* ... */ }
});
```

### `onDestroy`

[API Reference](/typedoc/interfaces/rivetkit.mod.ActorDefinition.html)

The `onDestroy` hook is called when the actor is being permanently destroyed. Can be async. Use this for final cleanup operations like closing external connections, releasing resources, or performing any last-minute state persistence.

```typescript
import { actor } from "rivetkit";

const gameSession = actor({
  onDestroy: (c) => {
    // Clean up any external resources
  },
  actions: { /* ... */ }
});
```

### `onWake`

[API Reference](/typedoc/interfaces/rivetkit.mod.ActorDefinition.html)

This hook is called any time the actor is started (e.g. after restarting, upgrading code, or crashing). Can be async.

This is called after the actor has been initialized but before any connections are accepted.

Use this hook to set up any resources or start any background tasks, such as `setInterval`.

```typescript
import { actor } from "rivetkit";

const counter = actor({
  state: { count: 0 },
  vars: { intervalId: null as NodeJS.Timeout | null },

  onWake: (c) => {
    console.log('Actor started with count:', c.state.count);

    // Set up interval for automatic counting
    const intervalId = setInterval(() => {
      c.state.count++;
      c.broadcast("countChanged", c.state.count);
      console.log('Auto-increment:', c.state.count);
    }, 10000);

    // Store interval ID in vars to clean up later if needed
    c.vars.intervalId = intervalId;
  },

  actions: {
    stop: (c) => {
      if (c.vars.intervalId) {
        clearInterval(c.vars.intervalId);
        c.vars.intervalId = null;
      }
    }
  }
});
```

### `onSleep`

[API Reference](/typedoc/interfaces/rivetkit.mod.ActorDefinition.html)

This hook is called when the actor is going to sleep. Can be async. Use this to clean up resources, close connections, or perform any shutdown operations.

This hook may not always be called in situations like crashes or forced terminations. Don't rely on it for critical cleanup operations.

Not supported on Cloudflare Workers.

```typescript
import { actor } from "rivetkit";

const counter = actor({
  state: { count: 0 },
  vars: { intervalId: null as NodeJS.Timeout | null },

  onWake: (c) => {
    // Set up interval when actor wakes
    c.vars.intervalId = setInterval(() => {
      c.state.count++;
      console.log('Auto-increment:', c.state.count);
    }, 10000);
  },

  onSleep: (c) => {
    console.log('Actor going to sleep, cleaning up...');

    // Clean up interval before sleeping
    if (c.vars.intervalId) {
      clearInterval(c.vars.intervalId);
      c.vars.intervalId = null;
    }

    // Perform any other cleanup
    console.log('Final count:', c.state.count);
  },

  actions: { /* ... */ }
});
```

### `onStateChange`

[API Reference](/typedoc/interfaces/rivetkit.mod.ActorDefinition.html)

Called whenever the actor's state changes. Cannot be async. This is often used to broadcast state updates.

```typescript
import { actor } from "rivetkit";

const counter = actor({
  state: { count: 0 },

  onStateChange: (c, newState) => {
    // Broadcast the new count to all connected clients
    c.broadcast('countUpdated', {
      count: newState.count
    });
  },
  
  actions: {
    increment: (c) => {
      c.state.count++;
      return c.state.count;
    }
  }
});
```

### `createConnState` and `connState`

[API Reference](/typedoc/interfaces/rivetkit.mod.ActorDefinition.html)

There are two ways to define the initial state for connections:
1. `connState`: Define a constant object that will be used as the initial state for all connections
2. `createConnState`: A function that dynamically creates initial connection state based on connection parameters. Can be async.

### `onBeforeConnect`

[API Reference](/typedoc/interfaces/rivetkit.mod.BeforeConnectContext.html)

The `onBeforeConnect` hook is called whenever a new client connects to the actor. Can be async. Clients can pass parameters when connecting, accessible via `params`. This hook is used for connection validation and can throw errors to reject connections.

The `onBeforeConnect` hook does NOT return connection state - it's used solely for validation.

```typescript
import { actor } from "rivetkit";

// Helper function to validate tokens
function validateToken(token: string): boolean {
  return token.startsWith("valid_");
}

interface ConnParams {
  authToken?: string;
  userId?: string;
  role?: string;
}

interface ConnState {
  userId: string;
  role: string;
  joinTime: number;
}

const chatRoom = actor({
  state: { messages: [] as string[] },

  // Method 1: Use a static default connection state
  connState: {
    userId: "anonymous",
    role: "guest",
    joinTime: 0,
  } as ConnState,

  // Method 2: Dynamically create connection state
  createConnState: (c, params: ConnParams): ConnState => {
    return {
      userId: params.userId || "anonymous",
      role: params.role || "guest",
      joinTime: Date.now()
    };
  },

  // Validate connections before accepting them
  onBeforeConnect: (c, params: ConnParams) => {
    // Validate authentication
    const authToken = params.authToken;
    if (!authToken || !validateToken(authToken)) {
      throw new Error("Invalid authentication");
    }

    // Authentication is valid, connection will proceed
    // The actual connection state will come from connState or createConnState
  },

  actions: {}
});
```

Connections cannot interact with the actor until this method completes successfully. Throwing an error will abort the connection. This can be used for authentication - see [Authentication](/docs/actors/authentication) for details.

### `onConnect`

[API Reference](/typedoc/interfaces/rivetkit.mod.ConnectContext.html)

Executed after the client has successfully connected. Can be async. Receives the connection object as a second parameter.

```typescript
import { actor } from "rivetkit";

interface ConnState {
  userId: string;
}

interface UserInfo {
  online: boolean;
  lastSeen: number;
}

const chatRoom = actor({
  state: { users: {} as Record<string, UserInfo>, messages: [] as string[] },
  connState: { userId: "" } as ConnState,

  onConnect: (c, conn) => {
    // Add user to the room's user list using connection state
    const userId = conn.state.userId;
    c.state.users[userId] = {
      online: true,
      lastSeen: Date.now()
    };

    // Broadcast that a user joined
    c.broadcast("userJoined", { userId, timestamp: Date.now() });

    console.log(`User ${userId} connected`);
  },

  actions: {}
});
```

Messages will not be processed for this actor until this hook succeeds. Errors thrown from this hook will cause the client to disconnect.

### `onDisconnect`

[API Reference](/typedoc/interfaces/rivetkit.mod.ActorDefinition.html)

Called when a client disconnects from the actor. Can be async. Receives the connection object as a second parameter. Use this to clean up any connection-specific resources.

```typescript
import { actor } from "rivetkit";

interface ConnState {
  userId: string;
}

interface UserInfo {
  online: boolean;
  lastSeen: number;
}

const chatRoom = actor({
  state: { users: {} as Record<string, UserInfo>, messages: [] as string[] },
  connState: { userId: "" } as ConnState,

  onDisconnect: (c, conn) => {
    // Update user status when they disconnect
    const userId = conn.state.userId;
    if (c.state.users[userId]) {
      c.state.users[userId].online = false;
      c.state.users[userId].lastSeen = Date.now();
    }

    // Broadcast that a user left
    c.broadcast("userLeft", { userId, timestamp: Date.now() });

    console.log(`User ${userId} disconnected`);
  },

  actions: {}
});
```

### `onRequest`

[API Reference](/typedoc/interfaces/rivetkit.mod.RequestContext.html)

The `onRequest` hook handles HTTP requests sent to your actor at `/actors/{actorName}/http/*` endpoints. Can be async. It receives the request context and a standard `Request` object, and should return a `Response` object or `void` to continue default routing.

See [Request Handler](/docs/actors/request-handler) for more details.

```typescript
import { actor } from "rivetkit";

const apiActor = actor({
  state: { requestCount: 0 },

  onRequest: (c, request) => {
    const url = new URL(request.url);
    c.state.requestCount++;

    if (url.pathname === "/api/status") {
      return new Response(JSON.stringify({
        status: "ok",
        requestCount: c.state.requestCount
      }), {
        headers: { "Content-Type": "application/json" }
      });
    }

    // Return a default response for unhandled paths
    return new Response("Not Found", { status: 404 });
  },

  actions: {}
});
```

### `onWebSocket`

[API Reference](/typedoc/interfaces/rivetkit.mod.WebSocketContext.html)

The `onWebSocket` hook handles WebSocket connections to your actor. Can be async. It receives the actor context and a `WebSocket` object. Use this to set up WebSocket event listeners and handle real-time communication.

See [WebSocket Handler](/docs/actors/websocket-handler) for more details.

```typescript
import { actor } from "rivetkit";

const realtimeActor = actor({
  state: { connectionCount: 0 },

  onWebSocket: (c, websocket) => {
    c.state.connectionCount++;
    
    // Send welcome message
    websocket.send(JSON.stringify({
      type: "welcome",
      connectionCount: c.state.connectionCount
    }));
    
    // Handle incoming messages
    websocket.addEventListener("message", (event) => {
      const data = JSON.parse(event.data);
      
      if (data.type === "ping") {
        websocket.send(JSON.stringify({
          type: "pong",
          timestamp: Date.now()
        }));
      }
    });
    
    // Handle connection close
    websocket.addEventListener("close", () => {
      c.state.connectionCount--;
    });
  },
  
  actions: { /* ... */ }
});
```

### `onBeforeActionResponse`

[API Reference](/typedoc/interfaces/rivetkit.mod.ActorDefinition.html)

The `onBeforeActionResponse` hook is called before sending an action response to the client. Can be async. Use this hook to modify or transform the output of an action before it's sent to the client. This is useful for formatting responses, adding metadata, or applying transformations to the output.

```typescript
import { actor } from "rivetkit";

const loggingActor = actor({
  state: { requestCount: 0 },

  onBeforeActionResponse: <Out>(c: unknown, actionName: string, args: unknown[], output: Out): Out => {
    // Log action calls
    console.log(`Action ${actionName} called with args:`, args);
    console.log(`Action ${actionName} returned:`, output);

    // Return the output unchanged (or transform as needed)
    return output;
  },

  actions: {
    getUserData: (c, userId: string) => {
      c.state.requestCount++;

      return {
        userId,
        profile: { name: "John Doe", email: "[email protected]" },
        lastActive: Date.now()
      };
    },

    getStats: (c) => {
      return {
        requestCount: c.state.requestCount,
        uptime: process.uptime()
      };
    }
  }
});
```

## Options

The `options` object allows you to configure various timeouts and behaviors for your actor.

```typescript
import { actor } from "rivetkit";

const myActor = actor({
  state: { count: 0 },

  options: {
    // Timeout for createVars function (default: 5000ms)
    createVarsTimeout: 5000,

    // Timeout for createConnState function (default: 5000ms)
    createConnStateTimeout: 5000,

    // Timeout for onConnect hook (default: 5000ms)
    onConnectTimeout: 5000,

    // Timeout for onSleep hook (default: 5000ms)
    onSleepTimeout: 5000,

    // Timeout for onDestroy hook (default: 5000ms)
    onDestroyTimeout: 5000,

    // Interval for saving state (default: 10000ms)
    stateSaveInterval: 10_000,

    // Timeout for action execution (default: 60000ms)
    actionTimeout: 60_000,

    // Max time to wait for background promises during shutdown (default: 15000ms)
    waitUntilTimeout: 15_000,

    // Timeout for connection liveness check (default: 2500ms)
    connectionLivenessTimeout: 2500,

    // Interval for connection liveness check (default: 5000ms)
    connectionLivenessInterval: 5000,

    // Prevent actor from sleeping (default: false)
    noSleep: false,

    // Time before actor sleeps due to inactivity (default: 30000ms)
    sleepTimeout: 30_000,

    // Whether WebSockets can hibernate for onWebSocket (default: false)
    // Can be a boolean or a function that takes a Request and returns a boolean
    canHibernateWebSocket: false,
  },

  actions: { /* ... */ }
});
```

| Option | Default | Description |
|--------|---------|-------------|
| `createVarsTimeout` | 5000ms | Timeout for `createVars` function |
| `createConnStateTimeout` | 5000ms | Timeout for `createConnState` function |
| `onConnectTimeout` | 5000ms | Timeout for `onConnect` hook |
| `onSleepTimeout` | 5000ms | Timeout for `onSleep` hook |
| `onDestroyTimeout` | 5000ms | Timeout for `onDestroy` hook |
| `stateSaveInterval` | 10000ms | Interval for persisting state |
| `actionTimeout` | 60000ms | Timeout for action execution |
| `waitUntilTimeout` | 15000ms | Max time to wait for background promises during shutdown |
| `connectionLivenessTimeout` | 2500ms | Timeout for connection liveness check |
| `connectionLivenessInterval` | 5000ms | Interval for connection liveness check |
| `noSleep` | false | Prevent actor from sleeping |
| `sleepTimeout` | 30000ms | Time before actor sleeps due to inactivity |
| `canHibernateWebSocket` | false | Whether WebSockets can hibernate (experimental) |

## Advanced

### Running Background Tasks

The `c.runInBackground` method allows you to execute promises asynchronously without blocking the actor's main execution flow. The actor is prevented from sleeping while the promise passed to `runInBackground` is still active. This is useful for fire-and-forget operations where you don't need to wait for completion.

Common use cases:
- **Analytics and logging**: Send events to external services without delaying responses
- **State sync**: Populate external databases or APIs with updates to actor state in the background

```typescript
import { actor } from "rivetkit";

interface PlayerInfo {
  joinedAt: number;
}

const gameRoom = actor({
  state: {
    players: {} as Record<string, PlayerInfo>,
    scores: {} as Record<string, number>
  },

  actions: {
    playerJoined: (c, playerId: string) => {
      c.state.players[playerId] = { joinedAt: Date.now() };

      // Send analytics event without blocking using waitUntil
      c.waitUntil(
        fetch('https://analytics.example.com/events', {
          method: 'POST',
          body: JSON.stringify({
            event: 'player_joined',
            playerId,
            timestamp: Date.now()
          })
        }).then(() => console.log('Analytics sent'))
      );

      return { success: true };
    },
  }
});
```

### Actor Shutdown Abort Signal

The `c.abortSignal` provides an `AbortSignal` that fires when the actor is stopping. Use this to cancel ongoing operations when the actor sleeps or is destroyed.

```typescript
import { actor } from "rivetkit";

const chatActor = actor({
  actions: {
    generate: async (c, prompt: string) => {
      const response = await fetch("https://api.example.com/generate", {
        method: "POST",
        body: JSON.stringify({ prompt }),
        signal: c.abortSignal
      });

      return await response.json();
    }
  }
});
```

See [Canceling Long-Running Actions](/docs/actors/actions#canceling-long-running-actions) for manually canceling operations on-demand.

### Using `ActorContext` Type Externally

When extracting logic from lifecycle hooks or actions into external functions, you'll often need to define the type of the context parameter. Rivet provides helper types that make it easy to extract and pass these context types to external functions.

```typescript
import { actor, ActorContextOf } from "rivetkit";

// Define the actor first
const myActor = actor({
  state: { count: 0 },
  actions: {}
});

// Then define functions using the actor's context type
function logActorStarted(c: ActorContextOf<typeof myActor>) {
  console.log(`Actor started with count: ${c.state.count}`);
}

// Usage example: call the function from inside the actor
const myActorWithHook = actor({
  state: { count: 0 },
  onWake: (c) => {
    console.log(`Actor woke up with count: ${c.state.count}`);
  },
  actions: {}
});
```

See [Types](/docs/actors/types) for more details on using `ActorContextOf`.

## Full Example

```typescript
import { actor } from "rivetkit";

interface CounterInput {
  initialCount?: number;
  stepSize?: number;
  name?: string;
}

interface CounterState {
  count: number;
  stepSize: number;
  name: string;
  requestCount: number;
}

interface ConnParams {
  userId: string;
  role: string;
}

interface ConnState {
  userId: string;
  role: string;
  connectedAt: number;
}

const counter = actor({
  // Default state (needed for type inference)
  state: {
    count: 0,
    stepSize: 1,
    name: "Unnamed Counter",
    requestCount: 0,
  } as CounterState,

  // Default connection state (needed for type inference)
  connState: {
    userId: "",
    role: "",
    connectedAt: 0,
  } as ConnState,

  // Initialize state with input
  createState: (c, input: CounterInput): CounterState => ({
    count: input.initialCount ?? 0,
    stepSize: input.stepSize ?? 1,
    name: input.name ?? "Unnamed Counter",
    requestCount: 0,
  }),

  // Initialize actor (run setup that doesn't affect initial state)
  onCreate: (c, input: CounterInput) => {
    console.log(`Counter "${input.name}" initialized`);
    // Set up external resources, logging, etc.
  },

  // Dynamically create connection state from params
  createConnState: (c, params: ConnParams): ConnState => {
    return {
      userId: params.userId,
      role: params.role,
      connectedAt: Date.now()
    };
  },

  // Lifecycle hooks
  onWake: (c) => {
    console.log(`Counter "${c.state.name}" started with count:`, c.state.count);
  },

  onStateChange: (c, newState) => {
    c.broadcast('countUpdated', {
      count: newState.count,
      name: newState.name
    });
  },

  onBeforeConnect: (c, params: ConnParams) => {
    // Validate connection params
    if (!params.userId) {
      throw new Error("userId is required");
    }
    console.log(`User ${params.userId} attempting to connect`);
  },

  onConnect: (c, conn) => {
    console.log(`User ${conn.state.userId} connected to "${c.state.name}"`);
  },

  onDisconnect: (c, conn) => {
    console.log(`User ${conn.state.userId} disconnected from "${c.state.name}"`);
  },

  // Transform all action responses
  onBeforeActionResponse: <Out>(c: unknown, actionName: string, args: unknown[], output: Out): Out => {
    // Log action calls
    console.log(`Action ${actionName} called`);
    return output;
  },

  // Define actions
  actions: {
    increment: (c, amount?: number) => {
      const step = amount ?? c.state.stepSize;
      c.state.count += step;
      return c.state.count;
    },

    getInfo: (c) => ({
      name: c.state.name,
      count: c.state.count,
      stepSize: c.state.stepSize,
      totalRequests: c.state.requestCount,
    }),
  }
});

export default counter;
```

_Source doc path: /docs/actors/lifecycle_

```

### reference/actors/request-handler.md

```markdown
# Low-Level HTTP Request Handler

> Source: `src/content/docs/actors/request-handler.mdx`
> Canonical URL: https://rivet.dev/docs/actors/request-handler
> Description: Actors can handle HTTP requests through the `onRequest` handler.

---
For most use cases, [actions](/docs/actors/actions) provide high-level API powered by HTTP that's easier to work with than low-level HTTP. However, low-level handlers are required when implementing custom use cases or integrating external libraries that need direct access to the underlying HTTP `Request`/`Response` objects or WebSocket connections.

## Handling HTTP Requests

The `onRequest` handler processes HTTP requests sent to your actor. It receives the actor context and a standard `Request` object and returns a `Response` object.

### Raw HTTP

```typescript
import { actor } from "rivetkit";

export const counterActor = actor({
    state: {
        count: 0,
    },
    // WinterTC compliant - accepts standard Request and returns standard Response
    onRequest: (c, request) => {
        const url = new URL(request.url);

        if (request.method === "GET" && url.pathname === "/count") {
            return Response.json({ count: c.state.count });
        }

        if (request.method === "POST" && url.pathname === "/increment") {
            c.state.count++;
            return Response.json({ count: c.state.count });
        }

        return new Response("Not Found", { status: 404 });
    },
    actions: {}
});
```

### Hono

```typescript
import { actor, ActorContextOf } from "rivetkit";
import { Hono } from "hono";

// Define the actor first
const counterActor = actor({
    state: { count: 0 },
    actions: {}
});

// Build router with typed context
function buildRouter(actorCtx: ActorContextOf<typeof counterActor>) {
    const app = new Hono();

    app.get("/count", (honoCtx) => {
        return honoCtx.json({ count: actorCtx.state.count });
    });

    app.post("/increment", (honoCtx) => {
        actorCtx.state.count++;
        return honoCtx.json({ count: actorCtx.state.count });
    });

    return app;
}

// Define the full actor with onRequest
export const counterActorWithRouter = actor({
    state: { count: 0 },
    vars: { app: null as Hono | null },
    createVars: () => ({
        app: null as Hono | null
    }),
    onRequest: async (c, request) => {
        // Build router lazily
        const app = buildRouter(c as ActorContextOf<typeof counterActor>);
        return await app.fetch(request);
    },
    actions: {}
});
```

See also the [raw fetch handler example](https://github.com/rivet-dev/rivet/tree/main/examples/raw-fetch-handler).

## Sending Requests To Actors

### Via RivetKit Client

Use the `.fetch()` method on an actor handle to send HTTP requests to the actor's `onRequest` handler. This can be executed from either your frontend or backend.

```typescript {{"title":"registry.ts"}} @hide
import { actor, setup } from "rivetkit";

export const counter = actor({
    state: { count: 0 },
    onRequest: (c, request) => {
        if (request.method === "POST") c.state.count++;
        return Response.json(c.state);
    },
    actions: {}
});

export const registry = setup({ use: { counter } });
```

```typescript {{"title":"client.ts"}}
import { createClient } from "rivetkit/client";
import type { registry } from "./registry";

const client = createClient<typeof registry>();

const actor = client.counter.getOrCreate(["my-counter"]);

// .fetch() is WinterTC compliant, it accepts standard Request and returns standard Response
const response = await actor.fetch("/");
const data = await response.json();
console.log(data); // { count: 0 }
```

### Via getGatewayUrl

Use `.getGatewayUrl()` to get the raw gateway URL for the actor. This is useful when you need to use the URL with external tools or custom HTTP clients.

```typescript {{"title":"registry.ts"}} @hide
import { actor, setup } from "rivetkit";

export const counter = actor({
    state: { count: 0 },
    onRequest: (c, request) => {
        if (request.method === "POST") c.state.count++;
        return Response.json(c.state);
    },
    actions: {}
});

export const registry = setup({ use: { counter } });
```

```typescript {{"title":"client.ts"}}
import { createClient } from "rivetkit/client";
import type { registry } from "./registry";

const client = createClient<typeof registry>();

const actor = client.counter.getOrCreate(["my-counter"]);

// Get the raw gateway URL
const gatewayUrl = await actor.getGatewayUrl();
// gatewayUrl = "https://...rivet.dev/..."

// Use with native fetch
const response = await fetch(`${gatewayUrl}/request/`);
const data = await response.json();
console.log(data); // { count: 0 }
```

### Via HTTP API

This handler can be accessed with raw HTTP using `https://api.rivet.dev/gateway/{actorId}/request/{...path}`.

For example, to call `POST /increment` on the counter actor above:

```typescript
// Replace with your actor ID and token
const actorId = "your-actor-id";
const token = "your-token";

const response = await fetch(
  `https://api.rivet.dev/gateway/${actorId}/request/increment`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
    },
  }
);
const data = await response.json();
console.log(data); // { count: 1 }
```

```bash
curl -X POST "https://api.rivet.dev/gateway/{actorId}/request/increment" \
  -H "Authorization: Bearer {token}"
```

The request is routed to the actor's `onRequest` handler where:

- `request.method` is `"POST"`
- `request.url` ends with `/increment` (the path after `/request/`)
- Headers, body, and other request properties are passed through unchanged

See the [HTTP API reference](/docs/actors/http-api) for more information on HTTP routing and authentication.

### Via Proxying Requests

You can proxy HTTP requests from your own server to actor handlers using the RivetKit client. This is useful when you need to add custom authentication, rate limiting, or request transformation before forwarding to actors.

```typescript
import { Hono } from "hono";
import { createClient } from "rivetkit/client";
import { serve } from "@hono/node-server";

const client = createClient();

const app = new Hono();

// Proxy requests to actor's onRequest handler
app.all("/actors/:id/:path{.*}", async (c) => {
    const actorId = c.req.param("id");
    const actorPath = (c.req.param("path") || "");

    // Forward to actor's onRequest handler
    const actor = client.counter.get(actorId);
    return await actor.fetch(actorPath, c.req.raw);
});

serve(app);
```

## Connection & Lifecycle Hooks

`onRequest` will trigger the `onBeforeConnect`, `onConnect`, and `onDisconnect` hooks. Read more about [lifecycle hooks](/docs/actors/lifecycle).

Requests in flight will be listed in `c.conns`. Read more about [connections](/docs/actors/connections).

## WinterTC Compliance

The `onRequest` handler is WinterTC compliant and will work with existing libraries using the standard `Request` and `Response` types.

## Limitations

- Does not support streaming responses & server-sent events at the moment. See the [tracking issue](https://github.com/rivet-dev/rivet/issues/3529).
- `OPTIONS` requests currently are handled by Rivet and are not passed to `onRequest`

## API Reference

- [`RequestContext`](/typedoc/interfaces/rivetkit.mod.RequestContext.html) - Context for HTTP request handlers
- [`ActorDefinition`](/typedoc/interfaces/rivetkit.mod.ActorDefinition.html) - Interface for defining request handlers

_Source doc path: /docs/actors/request-handler_

```

### reference/actors/kv.md

```markdown
# Low-Level KV Storage

> Source: `src/content/docs/actors/kv.mdx`
> Canonical URL: https://rivet.dev/docs/actors/kv
> Description: Use the built-in key-value store on ActorContext for durable string and binary data alongside actor state.

---
Every Rivet Actor includes a lightweight key-value store on `c.kv`. It is useful for dynamic keys, blobs, or data that does not fit well in structured state.

If your data has a known schema, prefer [state](/docs/actors/state). KV is best for flexible or user-defined keys.

## Basic Usage

Keys and values default to `text`, so you can use strings without extra options.

```typescript
import { actor } from "rivetkit";

const greetings = actor({
  state: {},
  actions: {
    setGreeting: async (c, userId: string, message: string) => {
      await c.kv.put(`greeting:${userId}`, message);
    },
    getGreeting: async (c, userId: string) => {
      return await c.kv.get(`greeting:${userId}`);
    }
  }
});
```

## Value Types

You can store binary values by passing `Uint8Array` or `ArrayBuffer` directly. Use `type` when reading to get the right return type.

```typescript
import { actor } from "rivetkit";

const assets = actor({
  state: {},
  actions: {
    putAvatar: async (c, bytes: Uint8Array) => {
      await c.kv.put("avatar", bytes);
    },
    getAvatar: async (c) => {
      return await c.kv.get("avatar", { type: "binary" });
    },
    putSnapshot: async (c, data: ArrayBuffer) => {
      await c.kv.put("snapshot", data);
    }
  }
});
```

TypeScript returns a concrete type based on the option you pass in:

```typescript
import { actor } from "rivetkit";

const example = actor({
  state: {},
  actions: {
    demo: async (c) => {
      const textValue = await c.kv.get("greeting");
      //    ^? string | null

      const bytes = await c.kv.get("avatar", { type: "binary" });
      //    ^? Uint8Array | null
    }
  }
});
```

## Key Types

Keys accept either `string` or `Uint8Array`. String keys are encoded as UTF-8 by default.

When listing by prefix, you can control how keys are decoded with `keyType`. Returned keys have the prefix removed.

```typescript
import { actor } from "rivetkit";

const example = actor({
  state: {},
  actions: {
    listGreetings: async (c) => {
      const results = await c.kv.list("greeting:", { keyType: "text" });

      for (const [key, value] of results) {
        console.log(key, value);
      }
    }
  }
});
```

If you use binary keys, set `keyType: "binary"` so the returned keys stay as `Uint8Array`.

## Batch Operations

KV supports batch operations for efficiency. Defaults are still `text` for both keys and values.

```typescript
import { actor } from "rivetkit";

const example = actor({
  state: {},
  actions: {
    batchOps: async (c) => {
      await c.kv.putBatch([
        ["alpha", "1"],
        ["beta", "2"],
      ]);

      const values = await c.kv.getBatch(["alpha", "beta"]);
    }
  }
});
```

## API Reference

- [`ActorContext`](/typedoc/interfaces/rivetkit.mod.ActorContext.html) - `c.kv` is available on the context

_Source doc path: /docs/actors/kv_

```