Direct VM API

npm install @rivet-dev/agentos

import { mkdirSync } from "node:fs";
import { resolve } from "node:path";
import pi from "@agentos-software/pi";
import { AgentOs } from "@rivet-dev/agentos";

// Create a VM directly with the AgentOS package — no actor runtime, no
// client/server split. `AgentOs.create()` boots the VM in-process.
mkdirSync(".agentos", { recursive: true });
const vm = await AgentOs.create({
	database: {
		type: "sqlite_file",
		path: resolve(".agentos/agentos.sqlite"),
	},
	software: [pi],
});

const result = await vm.process.exec("echo hello");
console.log(result.stdout); // "hello\n"

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

// One dedicated sidecar process hosting multiple VMs.
const sidecar = await AgentOs.createSidecar();
const a = await AgentOs.create({ sidecar: { kind: "explicit", handle: sidecar } });
const b = await AgentOs.create({ sidecar: { kind: "explicit", handle: sidecar } });

await a.dispose(); // tears down VM a only
await b.dispose();
await sidecar.dispose(); // tears down the shared process

await vm.filesystem.writeFile("/home/agentos/hello.txt", "Hello, world!");
const content = await vm.filesystem.readFile("/home/agentos/hello.txt");
console.log(new TextDecoder().decode(content));

await vm.filesystem.mkdir("/home/agentos/src");
await vm.filesystem.writeFiles([
	{ path: "/home/agentos/src/index.ts", content: "console.log('hi');" },
	{
		path: "/home/agentos/src/utils.ts",
		content: "export const add = (a: number, b: number) => a + b;",
	},
]);

const entries = await vm.filesystem.readdirRecursive("/home/agentos");
for (const entry of entries) {
	console.log(entry.type, entry.path);
}

await vm.createContext("analysis");
await vm.typescript.execute("const answer: number = 40", {
	contextId: "analysis",
});
const result = await vm.javascript.evaluate<number>("answer + 2", {
	contextId: "analysis",
});
console.log(result.outcome === "succeeded" ? result.value : result.error);

await vm.contexts.reset("analysis");
await vm.contexts.delete("analysis");

// One-shot execution
const result = await vm.process.exec("ls -la /home/agentos");
console.log(result.stdout);

// Long-running process with portable output and exit subscriptions.
await vm.filesystem.writeFile(
	"/tmp/server.mjs",
	'import http from "http"; http.createServer((req, res) => res.end("ok")).listen(3000); console.log("listening");',
);
const { pid } = await vm.process.spawn("node", ["/tmp/server.mjs"]);

vm.onProcessOutput(pid, (event) =>
	console.log(event.stream, new TextDecoder().decode(event.data)),
);
vm.onProcessExit(pid, (event) => console.log("exited:", event.exitCode));

// Write to stdin
await vm.process.writeStdin(pid, "some input\n");

// Stop or kill
await vm.process.signal(pid, "SIGTERM");

// openSession() negotiates ACP and durably records the session in SQLite.
await vm.sessions.open({
	agent: "pi",
	env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
	permissionPolicy: "ask",
});

// Native ACP updates and permission records share one session event union.
vm.onSessionEvent((event) => {
	if (event.type === "permission_request") {
		console.log("Permission:", event.requestId, event.toolCall);
	} else {
		console.log(event.durability, event);
	}
});

const result = await vm.sessions.prompt({
	content: [{ type: "text", text: "Write a hello world script" }],
});
console.log(result.message?.content ?? []);

// Unload releases the adapter but preserves SQLite history for restoration.
await vm.sessions.unload();

// Start a server inside the VM
await vm.filesystem.writeFile(
	"/tmp/app.mjs",
	'import http from "http"; http.createServer((req, res) => res.end("hello")).listen(3000);',
);
await vm.process.spawn("node", ["/tmp/app.mjs"]);

// httpRequest reaches services running in the VM with serializable DTOs.
const response = await vm.network.httpRequest({ port: 3000, path: "/" });
console.log(new TextDecoder().decode(response.body));

const job = vm.cron.schedule({
	id: "cleanup",
	schedule: "0 * * * *",
	action: { type: "exec", command: "rm", args: ["-rf", "/tmp/cache"] },
});
console.log("Scheduled:", job.id);

// Run an agent session on a schedule
vm.cron.schedule({
	schedule: "0 9 * * *",
	action: {
		type: "session",
		agentType: "pi",
		prompt: "Review the logs and summarize any errors",
		options: { cwd: "/workspace" },
	},
});

vm.onCronEvent((event) => {
	console.log("Cron event:", event.type, event.jobId);
});

console.log(vm.cron.list());

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

// Configure filesystem backends at boot. Native mount plugins (host
// directories, S3, etc.) are passed via `plugin`, each identified by an `id`
// and a `config` object.
const vm = await AgentOs.create({
  mounts: [
    // Host directory (read-only)
    {
      path: "/mnt/code",
      plugin: { id: "host_dir", config: { hostPath: "/path/to/repo" } },
      readOnly: true,
    },
    // S3 bucket
    {
      path: "/mnt/data",
      plugin: { id: "s3", config: { bucket: "my-bucket", prefix: "agent/" } },
    },
  ],
});

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

// The full AgentOs.create() configuration surface. The agentOS() actor accepts
// this same options object and layers persistence, sleep/wake, and preview URLs
// on top.
const vm = await AgentOs.create({
  // Filesystems to mount at boot. Use nodeModulesMount() to expose a host
  // node_modules tree at /root/node_modules.
  mounts: [nodeModulesMount("/path/to/project/node_modules")],
  // Software packages to install in the VM (see /docs/software)
  software: [pi],
  // Also install the default software bundle (sh + coreutils). Defaults to true;
  // set false for a bare VM with only the software you list.
  defaultSoftware: true,
  // Ports exempt from SSRF checks (for testing against host-side mock servers)
  loopbackExemptPorts: [3000],
  // Sidecar placement — defaults to the shared `default` pool
  sidecar: { kind: "shared" },
});

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

// ACP updates and interactive permission records share one durable event union.
const vm = await AgentOs.create({ software: [pi] });
await vm.sessions.open({ agent: "pi", permissionPolicy: "ask" });

// Runs for every event on this session.
vm.onSessionEvent((event) => {
	if (event.type === "permission_request") {
		console.log("Permission request:", event.requestId, event.toolCall);
	} else {
		console.log("Session update:", event.durability, event);
	}
});