General

Quickstart (Embedded)

Run a coding agent in an embedded agentOS VM from an existing Node.js application.

Use the embedded API when you want to run agentOS directly inside an existing Node.js application without Rivet Actors. Your application owns VM identity, persistence, and lifecycle.

Choosing between Actors and embedded

Use Rivet Actors when you want agentOS to manage persistence, distributed state, sleep and wake, multiplayer, and orchestration. Use the embedded API when your application needs direct VM control and will own those responsibilities itself.

	Embedded API	Actor
Persistence	In-memory unless you configure `database`, plus mounts	Actor SQLite injected automatically
Distributed state	Manage yourself	Built-in
Stateful VMs	Complex to run yourself	Built into Rivet
Sleep/wake	Manual `dispose()` / `create()`	Automatic
Events	Direct in-process callbacks	Broadcast to every connected client
Preview URLs	Serve them from your own application	Built-in signed URL server
Multiplayer	Fan out from your own application	Multiple clients per actor
Orchestration	VM-local cron while the VM is alive	Workflows, queues, and cron
Agent-to-agent	Bindings between VMs you own	Built into Rivet Actors
Authentication	Your application’s own	Docs

Quick Start

Install

Install the core VM API and the Pi coding agent:

npm install @rivet-dev/agentos-core @agentos-software/pi

Set your model API key

export ANTHROPIC_API_KEY=your-api-key

Create an embedded VM

import pi from "@agentos-software/pi";
import { AgentOs } from "@rivet-dev/agentos-core";

const apiKey = process.env.ANTHROPIC_API_KEY;
if (!apiKey) {
	throw new Error("Set ANTHROPIC_API_KEY before running this example.");
}

const vm = await AgentOs.create({ software: [pi] });

try {
	await vm.sessions.open({
		agent: "pi",
		env: { ANTHROPIC_API_KEY: apiKey },
	});

	await vm.sessions.prompt({
		content: [
			{
				type: "text",
				text: "Create /home/agentos/hello-world.js that prints hello world.",
			},
		],
	});

	const script = await vm.filesystem.readFile("/home/agentos/hello-world.js");
	console.log(new TextDecoder().decode(script));
} finally {
	await vm.dispose();
}

Run it

npx tsx quickstart.ts

AgentOs.create() returns a VM handle directly. There is no actor server or separate client, and the VM stays alive until you call dispose().

See Embedded VMs for lifecycle, persistence, configuration, and the shared sidecar, plus links to each capability page’s Embedded API section. Use the actor quickstart when you want built-in persistence, sleep and wake, multiplayer, preview URLs, and orchestration.