Cron Jobs and Scheduled Tasks

IMPORTANT: Before doing anything, you MUST read
BASE_SKILL.md
in this skill's directory. It contains essential guidance on debugging, error handling, state management, deployment, and project setup. Those rules and patterns apply to all RivetKit work. Everything below assumes you have already read and understood it.

Working Examples

If you need a reference implementation, read the raw working example code in these templates:

scheduling

Patterns for running durable cron jobs and scheduled tasks on Rivet Actors. Actor schedules are persistent timers owned by the engine, so a job keeps its deadline through actor sleep, restarts, upgrades, deploys, and crashes.

Starter Code

Start from the working Scheduling example on GitHub. It implements a reminder service with one-shot timers, a React frontend, and live trigger events.

The Scheduling API

The full API is documented in Scheduling. There are two methods, both available on the actor context:

Method	Behavior
`c.schedule.after(duration, actionName, ...args)`	Runs the named action after `duration` milliseconds.
`c.schedule.at(timestamp, actionName, ...args)`	Runs the named action at an exact epoch timestamp in milliseconds.

Key properties:

Durable: The schedule is persisted by the engine and the timer survives actor sleep, restart, upgrade, and crash. If the actor is asleep at the deadline, the engine wakes it to run the action. See Lifecycle.
Plain actions as callbacks: The scheduled callback is an ordinary action on the same actor, invoked by name. Arguments after the action name are forwarded positionally, for example
```
c.schedule.after(delayMs, "triggerReminder", reminder.id)
```
.
No cancellation API: Rivet does not currently support canceling a scheduled action. The pattern is a tombstone guard: remove the entry from state and have the scheduled action no-op when it cannot find its entry. The example's
```
cancelReminder
```
and
```
triggerReminder
```
actions implement exactly this.

Recurring Jobs Via Re-Arm

c.schedule

is one-shot, so recurring jobs are built by having the scheduled action re-arm itself at the end of each run:

typescript

import { actor } from "rivetkit";

const DAY_MS = 24 * 60 * 60 * 1000;

export const dailyReport = actor({
  state: { lastRunAt: 0 },
  actions: {
    runReport: (c) => {
      // Do the job's work, then record the run.
      c.state.lastRunAt = Date.now();
      // Re-arm the next run before returning.
      c.schedule.after(DAY_MS, "runReport");
    },
  },
});

Arm the first run from

onCreate

or a setup action; after that, the action keeps the chain alive by rescheduling itself.

Re-arming with

after

measures the next run from the end of the current one, so the cadence drifts later by the job's runtime on every cycle. If runs must stay aligned to a fixed cadence, re-arm with

c.schedule.at(c.state.lastRunAt + DAY_MS, "runReport")

instead.

The Scheduling example itself only uses one-shot reminders. A real re-arm implementation lives in the idle world actor, where the

collectProduction

action credits production, updates

lastCollectedAt

, and calls a

scheduleCollection

helper that re-arms with

c.schedule.after(delayMs, "collectProduction", { buildingId })

. It also shows catch-up handling: if the action runs late, it computes how many whole intervals elapsed since the last run and credits them in one batch before re-arming.

For multi-step jobs that need retries and progress tracking inside a single run, consider Workflows instead of chaining schedules.

Durability Comparison

Approach	Timer Durability	Horizontal Scaling	Deploys And Restarts
`setTimeout` / `setInterval`	In-process memory only	Every replica arms its own timer, so jobs run once per instance	All pending timers are lost on restart or crash
`node-cron` and similar libraries	In-process memory only	Every instance runs the job unless you add external locking	Schedule resets on deploy; runs missed during downtime are skipped
External cron service	Lives outside your app	Needs a public HTTP endpoint plus its own dedupe and retry state	Survives your deploys but is separate infrastructure to operate
Rivet Actor scheduling	Persisted by the engine as a durable timer	Exactly one actor per key, so the timer is armed once rather than once per replica	Survives actor sleep, restart, upgrade, and crash

Idempotency

A scheduled action can fire more than you expect: a crash between doing the work and re-arming can cause the action to run again, and because schedules cannot be cancelled, an action can fire for an entry that was already removed. Design handlers so a duplicate firing is harmless:

Store a run marker in state: Keep a
```
lastRunAt
```
timestamp or a sequence number in actor state and update it inside the action. On each firing, compute elapsed time since the marker and skip or batch accordingly. The idle world actor's
```
collectProduction
```
does this with
```
lastCollectedAt
```
and whole-interval batching.
Tombstone guard for cancelled entries: The example's
```
triggerReminder
```
looks the reminder up in
```
c.state.reminders
```
first and returns with a warning if it is gone, so a fire-after-cancel is a safe no-op.
Keep work and marker updates in the same action: Actor state writes are persisted with the action, so updating the marker in the same handler that does the work keeps the two consistent.

Topology

Topology	Use When	Example Key
Singleton job actor	One global job such as a nightly report or cleanup pass	`job["daily-report"]`
Actor per scheduled entity	Per-user or per-resource timers such as reminders, trials, or billing periods	`reminder[userId]`

The Scheduling example uses a single shared

reminderActor["main"]

key for demo simplicity. For production reminder systems, prefer one actor per user so timers, state, and load are isolated per entity. See Keys.

Reminder Service Example

Topic	Summary
Scheduling	One-shot timers armed with `c.schedule.after(delayMs, "triggerReminder", reminder.id)` or `c.schedule.at(timestamp, "triggerReminder", reminder.id)` .
State	JSON state holding `reminders` and `completedCount` ; the scheduled action mutates state when it fires.
Events	`triggerReminder` broadcasts a `reminderTriggered` event to all connected clients. See Events.
Cancellation	`cancelReminder` only removes the reminder from state; the scheduled action may still fire and no-ops via a state lookup guard.

Actors

Key:
```
reminderActor["main"]
```
Responsibility: Stores reminders in persistent state, arms a future self-action per reminder via
```
c.schedule
```
, marks reminders completed when the scheduled action fires, and broadcasts
```
reminderTriggered
```
to connected clients.

Actions

```
scheduleReminder
```
```
scheduleReminderAt
```
```
triggerReminder
```
```
getReminders
```
```
cancelReminder
```
```
getStats
```

Queues
- None
State
- JSON
- ```
reminders
```
- ```
completedCount
```

Lifecycle

mermaid

sequenceDiagram
	participant C as Client
	participant R as reminderActor
	participant E as Engine

	C->>R: scheduleReminder(message, delayMs)
	R->>E: schedule.after(delayMs, triggerReminder, id)
	Note over E: schedule persisted + alarm armed
	R-->>C: reminder
	Note over R: actor sleeps
	E->>R: alarm fires, actor wakes
	Note over R: triggerReminder(id) runs
	R-->>C: reminderTriggered event
	Note over R: recurring jobs re-arm here with schedule.after

Security Checklist

The example is intentionally open: any client can connect to the shared

["main"]

key and schedule or cancel anything. Treat all of the following as required extensions for production:

Validate schedule inputs: Clamp
```
delayMs
```
and
```
timestamp
```
from clients. Reject negative delays, timestamps in the past, and absurdly far-future deadlines, and bound message or payload sizes.
Never schedule client-chosen actions: Expose specific actions like
```
scheduleReminder
```
that internally arm a fixed callback. Do not pass a client-supplied action name or unchecked args into
```
c.schedule
```
.
Authenticate and scope keys: Add connection authentication and use per-user actor keys instead of one global key, so users cannot read or cancel each other's schedules.
Prune completed entries: The example's
```
reminders
```
array grows without bound. Remove or archive completed entries so state stays small.
Use stable IDs: Generate entry IDs with
```
crypto.randomUUID()
```
rather than timestamp-plus-random strings.

Reference Map

Actors

Access Control
Actions
Actor Keys
Actor Scheduling
Actor Statuses
AI and User-Generated Rivet Actors
Authentication
Communicating Between Actors
Connections
Custom Inspector Tabs
Debugging
Design Patterns
Destroying Actors
Errors
Fetch and WebSocket Handler
Helper Types
Icons & Names
Input Parameters
Lifecycle
Limits
Low-Level HTTP Request Handler
Low-Level KV Storage
Low-Level WebSocket Handler
Metadata
Next.js Quickstart
Node.js & Bun Quickstart
Queues & Run Loops
React Quickstart
Realtime
Rust Quickstart (Preview)
Sandbox Actor
Scaling & Concurrency
Sharing and Joining State
SQLite
SQLite + Drizzle
State & Storage
Testing
Troubleshooting
Types
Vanilla HTTP API
Versions & Upgrades
Workflows

Agent Os

Agent-to-Agent Communication
agentOS vs Sandbox
Authentication
Benchmarks
Configuration
Core Package
Cron Jobs
Deployment
Embedded LLM Gateway
Events
Filesystem
Limitations
LLM Credentials
Multiplayer
Networking & Previews
Overview
Permissions
Persistence & Sleep
Pi
Processes & Shell
Queues
Quickstart
Sandbox Mounting
Security & Auth
Security Model
Sessions
Software
SQLite
System Prompt
Tools
Webhooks
Workflow Automation

Clients

Node.js & Bun
React
Swift
SwiftUI

Connect

Deploy To Amazon Web Services Lambda
Deploying to AWS ECS
Deploying to Cloudflare Workers
Deploying to Freestyle
Deploying to Google Cloud Run
Deploying to Hetzner
Deploying to Kubernetes
Deploying to Railway
Deploying to Rivet Compute
Deploying to Supabase Functions
Deploying to Vercel
Deploying to VMs & Bare Metal

Cookbook

AI Agent
AI Agent Workspaces
Chat Room
Collaborative Text Editor
Cron Jobs and Scheduled Tasks
Database per Tenant
Deploying Rivet in a VPC or Air-Gapped Network
Live Cursors and Presence
Multiplayer Game

General

Actor Configuration
Architecture
Cross-Origin Resource Sharing
Documentation for LLMs & AI
Edge Networking
Endpoints
Environment Variables
HTTP Server
Logging
Pool Configuration
Production Checklist
Registry Configuration
Runtime Modes

Self Hosting

Configuration
Docker Compose
Docker Container
File System
FoundationDB (Enterprise)
Installing Rivet Engine
Kubernetes
Multi-Region
PostgreSQL
Production Checklist
Railway Deployment
Render Deployment
TLS & Certificates

cron-jobs

NPX Install

Tags

SKILL.md Content