Forking

import { createClient } from "rivetkit/client";
import type { registry } from "./quickstart/index";

const client = createClient<typeof registry>();
const sourceId = await client.document.getOrCreate(["doc-1"]).resolve();

// Fork doc-1 into a new actor with its own key. `input` reaches its onFork.
const draft = await client.document.fork(sourceId, {
	key: ["doc-1-draft"],
	input: { title: "Draft of doc-1" },
});

// The returned handle calls the new actor like any other.
await draft.write("A new opening paragraph");
console.log(await draft.read());

import { actor, setup } from "rivetkit";
import { db } from "rivetkit/db";

export const workspace = actor({
	db: db({
		onMigrate: async (db) => {
			await db.execute(
				"CREATE TABLE IF NOT EXISTS branch (id INTEGER PRIMARY KEY CHECK (id = 1), label TEXT)",
			);
		},
	}),

	// Runs in the new actor and receives the input that `branch` passed to fork.
	onFork: async (c, fork) => {
		const label =
			typeof fork.input === "string" ? fork.input.slice(0, 100) : null;
		await c.db.execute(
			"INSERT OR REPLACE INTO branch (id, label) VALUES (1, ?)",
			label,
		);
	},

	actions: {
		// Forks this actor and returns the new actor's ID.
		branch: async (c, label: string): Promise<string> => {
			const client = c.client<typeof registry>();
			const copy = await client.workspace.fork(c.actorId, {
				input: label,
			});
			return await copy.resolve();
		},
	},
});

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

import { actor } from "rivetkit";
import { db } from "rivetkit/db";
import { z } from "zod";

const ForkInput = z.object({ label: z.string().max(100) });

const agent = actor({
	db: db({
		onMigrate: async (db) => {
			await db.execute(`
				CREATE TABLE IF NOT EXISTS fork_info (
					id INTEGER PRIMARY KEY CHECK (id = 1),
					source_id TEXT NOT NULL,
					label TEXT
				);
			`);
		},
	}),

	onFork: async (c, fork) => {
		// The source's pending schedules and cron jobs were copied with its database.
		// Cancel them so the fork does not repeat the source's work.
		for (const event of await c.schedule.list()) {
			await c.schedule.cancel(event.id);
		}
		for (const job of await c.cron.list()) {
			await c.cron.delete(job.name);
		}

		// fork.actorId, fork.key and fork.forkedAt come from Rivet. fork.input comes
		// from the caller, so it is validated, and invalid input is ignored rather
		// than thrown, since a throw fails the start and onFork runs again.
		const input = ForkInput.safeParse(fork.input);

		// INSERT OR REPLACE keeps the hook safe to run twice.
		await c.db.execute(
			"INSERT OR REPLACE INTO fork_info (id, source_id, label) VALUES (1, ?, ?)",
			fork.actorId,
			input.success ? input.data.label : null,
		);
	},

	actions: {},
});

import { actor } from "rivetkit";

const document = actor({
	actions: {
		// The actor this one was forked from, or null for an original.
		forkedFrom: (c) => c.forkChain.at(-1)?.actorId ?? null,

		// Every fork behind this actor, oldest first.
		lineage: (c) =>
			c.forkChain.map((link) => ({
				actorId: link.actorId,
				key: link.key,
				forkedAt: new Date(link.forkedAt).toISOString(),
			})),
	},
});

import { createClient } from "rivetkit/client";
import type { registry } from "./index";

// Runs on your backend. The endpoint carries your Rivet token.
const client = createClient<typeof registry>();

// A token that can fork doc-1 into new actors, and nothing else.
const sourceId = await client.document.getOrCreate(["doc-1"]).resolve();
const { token, expiresAt } = await client.auth.issueToken({
	subject: "user-123",
	expiresIn: 900,
	grants: [
		{ resource: "actor", target: { id: sourceId }, operations: ["fork"] },
		{ resource: "actor", target: "any", operations: ["create"] },
	],
});

curl -X POST "$RIVET_API/namespaces?wait=settled" \
  -H "Authorization: Bearer $RIVET_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"staging-copy","fork_from":"production"}'