100 lines
4.2 KiB
Markdown
100 lines
4.2 KiB
Markdown
# Runtime Modes
|
|
|
|
> Source: `src/content/docs/general/runtime-modes.mdx`
|
|
> Canonical URL: https://rivet.dev/docs/general/runtime-modes
|
|
> Description: RivetKit supports two runtime modes for running your actors:
|
|
|
|
---
|
|
- **Serverless**: Default mode. Responds to HTTP requests and scales automatically.
|
|
- **Runners**: Background processes without HTTP endpoints. Only needed for advanced scenarios.
|
|
|
|
## Serverless
|
|
|
|
Serverless is the default and recommended mode. Rivet sends HTTP requests to your backend to run actor logic, allowing your infrastructure to scale automatically.
|
|
|
|
### Benefits
|
|
|
|
- **Platform support**: Works with serverless platforms (Vercel, Cloudflare Workers, etc.)
|
|
- **Scale to zero**: No cost when idle
|
|
- **Edge deployments**: Easier to deploy to edge locations
|
|
- **Preview deployments**: Integrates with preview deployments on platforms like Vercel and Railway
|
|
- **Efficient autoscaling**: Request-based autoscaling can be faster and more efficient than CPU-based autoscaling depending on the platform
|
|
|
|
### Example
|
|
|
|
See [Server Setup](/docs/general/http-server/) for more configuration options.
|
|
|
|
### Architecture
|
|
|
|
When a client creates an actor, it sends a request to the Rivet Engine. The engine then calls `GET /api/rivet/start` on your serverless backend to run the actor.
|
|
|
|
<img src={imgServerless.src} alt="Serverless architecture diagram" />
|
|
|
|
### Advanced
|
|
|
|
#### Endpoints
|
|
|
|
Rivet exposes the following endpoints:
|
|
|
|
- `GET /api/rivet/metadata`: Validates configuration
|
|
- `GET /api/rivet/start`: Runs an actor
|
|
|
|
You should never call these endpoints yourself, this is included purely for comprehension of how Rivet works under the hood.
|
|
|
|
#### Timeouts
|
|
|
|
Serverless platforms like Vercel have function timeouts. Rivet handles this automatically by migrating actors between function invocations, preserving state through `ctx.state`. Write your code as if it runs forever, Rivet handles the rest.
|
|
|
|
Read more about [how we handle timeouts](/blog/2025-10-20-how-we-built-websocket-servers-for-vercel-functions/#timeouts-and-failover).
|
|
|
|
#### Shutdown Sequence
|
|
|
|
Each serverless request has a configurable lifespan (`requestLifespan`, default: 60 minutes). Set this to match your platform's function timeout (e.g. `requestLifespan: 3600` for Vercel Pro).
|
|
|
|
When the request nears its lifespan, the engine reserves a grace period (`serverless_drain_grace_period`, default: 10 seconds) at the end to gracefully stop actors. For example, with a 3600-second lifespan, actors begin stopping at 3590 seconds. After the full lifespan elapses, the connection is forcibly closed and any remaining actors are rescheduled.
|
|
|
|
See [Limits](/docs/actors/limits#serverless-shutdown) for configuration details.
|
|
|
|
## Runners
|
|
|
|
Runners run actors as long-running background processes without exposing an HTTP endpoint.
|
|
|
|
### When to Use Runners
|
|
|
|
- **No HTTP server**: Your app does not or cannot expose an HTTP server
|
|
- **No load balancer**: You don't have a load balancer to distribute HTTP requests across your servers
|
|
- **Custom scaling**: You have custom scaling requirements
|
|
|
|
### Example
|
|
|
|
The runner runs in the background, ready to run actors.
|
|
|
|
### Architecture
|
|
|
|
On startup, your backend calls `registry.startEnvoy()` which opens a persistent connection to the Rivet Engine. When a client creates an actor, the engine sends a command through this connection to start the actor on your backend.
|
|
|
|
<img src={imgRunners.src} alt="Runners architecture diagram" />
|
|
|
|
### Configuration
|
|
|
|
#### Runner Pool
|
|
|
|
Use `RIVET_RUNNER` to assign runners to a pool. This lets you control which runners handle specific actors.
|
|
|
|
```bash
|
|
RIVET_RUNNER=gpu-workers
|
|
```
|
|
|
|
See [Pool Configuration](/docs/general/pool-configuration) for how pools are scaled, drained on version upgrades, and rate-limited during actor eviction.
|
|
|
|
## Comparison
|
|
|
|
| Mode | Method | Use Case |
|
|
|------|--------|----------|
|
|
| Auto | `registry.start()` | Simplest setup. Starts server, serves static files, and runs actors. |
|
|
| Serverless | `registry.serve()` | Fetch handler for serverless platforms |
|
|
| Serverless | `registry.handler()` | Integrating with existing routers (Hono, Elysia, etc.) |
|
|
| Runner | `registry.startEnvoy()` | Long-running processes without HTTP endpoints |
|
|
|
|
_Source doc path: /docs/general/runtime-modes_
|