Platform

Rivet Actors

Run agentOS natively as Rivet Actors.

Rivet is agentOS’s native framework. The agentOS() function returns an ordinary Rivet Actor, so each agentOS VM is a directly addressable actor with its own durable filesystem, state, and session history—no adapter layer required.

View the complete example →

Quickstart

Create a project

mkdir my-agent && cd my-agent
npm init -y
npm pkg set type=module
npm add @rivet-dev/agentos @agentos-software/pi
npm add --save-dev tsx typescript

Create an agentOS actor

Create server.ts. The agentOS() call returns a normal Rivet Actor definition, and setup() registers it with the Rivet runtime:

import { agentOS, setup } from "@rivet-dev/agentos";
import pi from "@agentos-software/pi";

const vm = agentOS({
  software: [pi],
});

export const registry = setup({ use: { vm } });
registry.start();

Connect to the actor

Create client.ts to address an actor by name, subscribe to its events, open a session, and send a prompt:

import { createClient } from "@rivet-dev/agentos/client";
import type { registry } from "./server";

const client = createClient<typeof registry>({
	endpoint: "http://localhost:6420",
});
const handle = client.vm.getOrCreate("my-agent");

// Subscribe to streaming events. The payload is inferred from the event schema.
const conn = handle.connect();
conn.on("sessionEvent", (event) => {
	console.log(event);
});

// Open a durable session and send a prompt.
await handle.sessions.open({
	agent: "pi",
	env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
});
await handle.sessions.prompt({
	content: [
		{ type: "text", text: "Write a hello world script to /workspace/hello.js" },
	],
});

// Read the file the agent created
const content = await handle.filesystem.readFile("/workspace/hello.js");
console.log(new TextDecoder().decode(content));

Run locally

Start the actor, then run the client in a second terminal with the provider key required by your model:

# Terminal 1
npx tsx server.ts

# Terminal 2
ANTHROPIC_API_KEY=... npx tsx client.ts

Add orchestration

Because an agentOS VM is a Rivet Actor, you can compose it with Rivet’s orchestration primitives:

Durable workflows — Run multi-step agent tasks that retry and resume after crashes.
Multiplayer agents — Stream agent output to multiple connected clients in real time.
Agent-to-agent systems — Connect isolated agents through typed bindings and durable pipelines.
Scheduled agents — Run commands and agent sessions on timers or cron schedules.
Human-in-the-loop flows — Pause for tool approval and resume from durable event history.