Core Package

npm install @rivet-dev/agentos-core

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

// Create a VM directly with the core package — no actor runtime, no
// client/server split. `AgentOs.create()` boots the VM in-process.
const vm = await AgentOs.create({ software: [pi] });

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

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

// 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.writeFile("/home/agentos/hello.txt", "Hello, world!");
const content = await vm.readFile("/home/agentos/hello.txt");
console.log(new TextDecoder().decode(content));

await vm.mkdir("/home/agentos/src");
await vm.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.readdirRecursive("/home/agentos");
for (const entry of entries) {
  console.log(entry.type, entry.path);
}

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

// Long-running process with streaming output. spawn() returns synchronously;
// stdout/stderr are delivered through the callbacks you pass in.
await vm.writeFile(
  "/tmp/server.mjs",
  'import http from "http"; http.createServer((req, res) => res.end("ok")).listen(3000); console.log("listening");',
);
const { pid } = vm.spawn("node", ["/tmp/server.mjs"], {
  onStdout: (data) => console.log("stdout:", new TextDecoder().decode(data)),
});

vm.onProcessExit(pid, (exitCode) => console.log("exited:", exitCode));

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

// Stop or kill
vm.stopProcess(pid);

// createSession() resolves to a session record. All session operations take
// its `sessionId`.
const { sessionId } = await vm.createSession("pi", {
  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
});

// Stream session events (each event is a JSON-RPC notification).
vm.onSessionEvent(sessionId, (event) => {
  console.log(event.method, event.params);
});

// Observe permission requests from the agent.
vm.onPermissionRequest(sessionId, (request) => {
  console.log("Permission:", request.description ?? request.permissionId);
});

// Send a prompt. prompt() resolves to { response, text }, where `text` is the
// accumulated agent message text and `response` is the raw JSON-RPC response.
const { text } = await vm.prompt(sessionId, "Write a hello world script");
console.log(text);

vm.closeSession(sessionId);

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

// Fetch from it — fetch(port, Request) reaches services running in the VM.
const response = await vm.fetch(3000, new Request("http://vm/"));
console.log(await response.text());

const job = vm.scheduleCron({
  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.scheduleCron({
  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.listCronJobs());

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

// 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-core";
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],
  // Extra instructions appended to agent system prompts
  additionalInstructions: "Always write tests first.",
  // Sidecar placement — defaults to the shared `default` pool
  sidecar: { kind: "shared" },
});

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

// With the core package, session events and permission requests are observed
// per-session on the AgentOs instance (there is no actor-factory hook).
const vm = await AgentOs.create({ software: [pi] });
const { sessionId } = await vm.createSession("pi");

// Runs for every event on this session.
vm.onSessionEvent(sessionId, (event) => {
  console.log("Session event:", sessionId, event.method);
});

// Fires when the agent requests permission.
vm.onPermissionRequest(sessionId, (request) => {
  console.log("Permission request:", sessionId, request.permissionId);
});