Use a Sandbox from Any Actor

npm add @rivet-dev/sandbox-adapter

import { posix } from "node:path";
import type { Sandbox, SandboxActorContext } from "@rivet-dev/sandbox-adapter";
import { dockerProvider } from "@rivet-dev/sandbox-adapter/docker";
import { actor, event, setup } from "rivetkit";

// One provider object serves every Actor of this definition.
const provider = dockerProvider({ image: "ubuntu:24.04" });

interface BuildState {
	sandboxId: string | null;
}

export const build = actor({
	state: { sandboxId: null } as BuildState,
	events: {
		// Command output, as it arrives.
		output: event<string>(),
	},
	actions: {
		run: async (c, command: string) => {
			const sandbox = await openSandbox(c, c.state);
			const decoder = new TextDecoder();
			return sandbox.exec(command, {
				cwd: sandbox.cwd,
				timeoutMs: 60_000,
				// Stops the command if the Actor shuts down.
				signal: c.abortSignal,
				onData: (chunk) => c.broadcast("output", decoder.decode(chunk, { stream: true })),
			});
		},
		saveFile: async (c, path: string, content: string) => {
			const sandbox = await openSandbox(c, c.state);
			const target = posix.resolve(sandbox.cwd, path);
			await sandbox.mkdir(posix.dirname(target));
			await sandbox.writeFile(target, content);
		},
		readFile: async (c, path: string) => {
			const sandbox = await openSandbox(c, c.state);
			const bytes = await sandbox.readFile(posix.resolve(sandbox.cwd, path));
			return new TextDecoder().decode(bytes);
		},
	},
	// The sandbox stops while the Actor sleeps and is removed along with the Actor.
	onSleep: async (c) => {
		if (c.state.sandboxId) await provider.suspend?.(c, c.state.sandboxId);
	},
	onDestroy: async (c) => {
		if (c.state.sandboxId) await provider.destroy?.(c, c.state.sandboxId);
	},
});

// Connects to this Actor's sandbox. The first call creates it.
async function openSandbox(c: SandboxActorContext, state: BuildState): Promise<Sandbox> {
	const existing = state.sandboxId ? await provider.connect(c, state.sandboxId) : undefined;
	if (existing) return existing;
	state.sandboxId = await provider.create(c);
	const sandbox = await provider.connect(c, state.sandboxId);
	if (!sandbox) throw new Error(`Sandbox ${state.sandboxId} was not found right after it was created.`);
	return sandbox;
}

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

registry.start();

docker run --rm --entrypoint /bin/sh my-image -c 'for t in tail cat mkdir rm touch stat; do command -v "$t" >/dev/null || echo "missing: $t"; done; [ -w /tmp ] || echo "not writable: /tmp"'

import {
	type RemoteProcess,
	runRemoteProcess,
	type Sandbox,
	type SandboxProvider,
} from "@rivet-dev/sandbox-adapter";

// The client of your sandbox service.
export interface VmClient {
	create(): Promise<string>;
	// Starts a stopped VM. Returns false when the VM no longer exists.
	start(id: string): Promise<boolean>;
	stop(id: string): Promise<void>;
	delete(id: string): Promise<void>;
	spawn(id: string, command: string, options: { cwd: string; env?: Record<string, string> }): Promise<RemoteProcess>;
	readFile(id: string, path: string): Promise<Uint8Array>;
	writeFile(id: string, path: string, content: string): Promise<void>;
	mkdir(id: string, path: string): Promise<void>;
	isDirectory(id: string, path: string): Promise<boolean>;
	list(id: string, path: string): Promise<string[]>;
	exists(id: string, path: string): Promise<boolean>;
}

export function vmProvider(vms: VmClient): SandboxProvider {
	const cwd = "/workspace";
	return {
		name: "my-vms",
		cwd,
		create: () => vms.create(),
		connect: async (_c, id) => {
			if (!(await vms.start(id))) return undefined;
			await vms.mkdir(id, cwd);
			return vmSandbox(vms, id, cwd);
		},
		suspend: (_c, id) => vms.stop(id),
		destroy: (_c, id) => vms.delete(id),
	};
}

function vmSandbox(vms: VmClient, id: string, cwd: string): Sandbox {
	return {
		cwd,
		exec: async (command, options) =>
			// Streams output and applies the timeout and abort signal.
			runRemoteProcess(await vms.spawn(id, command, { cwd: options.cwd, env: options.env }), options),
		readFile: (path) => vms.readFile(id, path),
		writeFile: (path, content) => vms.writeFile(id, path, content),
		mkdir: (path) => vms.mkdir(id, path),
		stat: async (path) => ({ isDirectory: await vms.isDirectory(id, path) }),
		readdir: (path) => vms.list(id, path),
		exists: (path) => vms.exists(id, path),
	};
}