What are Actors?
Actors are a simple and powerful architecture. Think of actors as independent workers that:
- Maintain their own isolated, durable state in memory (survives crashes and upgrades)
- Communicate only through remote procedure calls - no shared state
- Scale infinitely, start instantly, and sleep when not in use
- Deploy globally at the edge (close to users)
These characteristics provide the following benefits:
- Complex infrastructure (e.g., caches, queues, pub/sub) can be replaced with actors, which is a simpler architecture
- Improve performance by combining compute (i.e., "RPC") with data (i.e., "state")
- Provide natural fault tolerance - state is durable and failures don't cascade
- Lower latency for users by running at the edge and combining compute/data
Core concepts
- Remote Procedure Call (RPC) is how clients communicate with actors and how actors communicate with each other.
- State is the data belonging to each actor. State cannot be shared between actors. State is stored in memory (unless it's too large) for fast reads and writes. State is durable and will always survive a crash or upgrade. You can update state without having to do anything special.
- Events are used for real-time communication between clients and actors. Clients can subscribe to events with
actor.on("myEvent"), and actors can publish events withthis.broadcast("myEvent")orconnection.send("myEvent"). - Connections represent a client that's currently connected to the actor. Connections have their own state, e.g.,
userId. You can useonConnectto authenticate connections before they can communicate with the actor.
To read more about architecting actors for scale, see here.
Actor architecture vs. server and container architecture
Servers and containers and actors handle state and compute very differently:
| Feature | Servers and Containers | Actors |
|---|---|---|
| Compute and State | Separate compute (application layer) from state (databases) | Keep state and compute together |
| Scaling | Need external services (load balancers, databases) to scale | Cheaper & automatically distribute load |
| Performance | Performance can be limited by network latency & complex locking mechanisms | Optimized performance by co-locating compute and state |
| Latency | Typically higher latency due to centralized data centers & database | Lower latency by deploying at the edge, closer to users |
| High Availability | Need manual configuration for high availability and fault tolerance | Provide built-in durability for crashes and fault isolation to prevent cascading failures |
| Resource Efficiency | Run continuously regardless of load, wasting resources when idle | Automatically sleep when inactive and wake instantly when needed |
| DevOps Overhead | Requires significant DevOps effort for setup and maintenance | Minimal DevOps overhead due to simpler, on-demand architecture |
Builds
Builds contain the code required to run an actor. Builds are uploaded to Rivet when running rivet deploy. Each actor is associated with a single build ID.
When a new build is uploaded, all actors are upgraded to use the new build. This process is usually transparent to you since the state is durable.
Actor and build tags
Tags are a powerful way of managing actors at scale. Tags can be any set of key-value pairs you choose. They allow you to easily choose which actors to communicate with, create fine-grained security rules, and enhance monitoring.
Structuring tags
While you can choose anything you'd like for your actor's tags, here are a few guidelines to consider:
- Actors and builds almost always have a
nametag defining what type of actor this is. For example,name=user,name=channel, orname=document. An actor'snametag is usually identical to the build'snametag. - Actors often have a unique ID associated with them as a tag. For example,
userId=1234,channel=memes,documentId=1234. - Actors and builds sometimes have an
ownertag indicating what service created the actor. For example,owner=apiandowner=terraform. - For larger projects, actors and builds sometimes have an
apptag to group the product an actor belongs to together. For example,app=socialandapp=store.
Note
Tags are not intended for storing large amounts of data (e.g., descriptions or long lists of items). They're intended purely for organizing and filtering actors/builds.
Example architectures
See the use cases for explanations of example actor architectures.