ActorCore is still pre-v1.0. Please help us by report bugs on GitHub Issues!

Create New Project

1

Create Project with CLI

Run this command:

npx create-actor@latest

Follow the prompts:

  1. Where would you like to create your project? - Choose your project directory
  2. To which platform would you like to deploy? - Select Rivet
  3. Which template would you like to use? - Select counter, or your template of choice

The CLI will set up your project and install all dependencies automatically.

2

Deploy to Rivet

Deploy your project to Rivet with:

cd your-project
npm run deploy

This will prompt you to:

  1. Login to Rivet and create a project
  2. Select an environment

After successful deployment, you’ll receive important URLs:

  • Actor Manager URL: Used for client connections to your actors
  • Actors Dashboard: Manage deployed actors and view their status
  • Builds Dashboard: Monitor build history and deployment logs

Make sure to save your Actor Manager URL as you’ll need it to connect from your client code.

3

Test

Update tests/client.ts to use the deployed endpoint. Replace the local endpoint in client.ts with your Rivet deployment URL:

tests/client.ts
import { createClient } from "actor-core/client";
import type { App } from "../src/app";

// Replace this URL with your Actor Manager URL from the deployment output
const client = createClient<App>("https://your-actor-manager-url-from-deployment.rivet.run:443");

async function main() {
	const counter = await client.counter.get();
	
	counter.on("newCount", (count: number) => console.log("Event:", count));
	
	const out = await counter.increment(5);
	console.log("Action:", out);
	
	await counter.dispose();
}

main();

Then run the client:

npx tsx tests/client.ts
# Outputs:
# Event: 5
# Action: 5

Run this again to see the state update as the actor maintains its state between calls.

4

Monitor

Monitor your actors, builds, and performance through the Rivet Hub using the links provided in the deployment output:

  • Actors: View and manage your deployed actors
  • Builds: Review build history and logs
  • Actor Manager: Access the actor manager endpoint for direct connections

Visit the Rivet Dashboard to view your project.

Accessing Rivet Context

Rivet’s ActorContext can be accessed from createVars.

import { actor } from "actor-core";

const myActor = actor({
  // Load Rivet-specific variables
  createVars: (c, rivet) => ({
	rivet: rivet.ctx,
  }),
  actions: {
	foo: async (c) => {
	  // Access ActorContext
	  c.log.info(`Region: ${c.vars.rivet.metadata.region.name}`);
	  await c.vars.rivet.kv.get("foo");
	},
  }
});

Available Regions

Rivet supports deploying your actors to multiple regions automatically. You can specify region preferences in your Rivet project settings in the Rivet Hub.

See available regions here.

Next Steps