Quickstart (Embedded)

Run an agentOS VM directly inside a Node.js application.

@rivet-dev/agentos-core runs VMs inside your Node.js process. Your application owns VM identity, persistence, and lifecycle, and AgentOs.create() returns a VM handle directly.

Install

npm install @rivet-dev/agentos-core

Create a VM

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

// `AgentOs.create()` boots a VM inside this process and returns a handle to it.
const vm = await AgentOs.create();

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

The VM remains active until dispose() is called. Its filesystem is in memory by default; see Persistence to keep files across VM recreation.

Configuration

The embedding process is trusted, so it can also give the VM access to host resources:

host functions implemented as in-process callbacks;
host-directory and other mounts;
local .aospkg paths;
explicit ownership of a shared sidecar process.

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

// Common AgentOs.create() configuration. The embedding process is trusted, so
// it may also configure host resources such as host directories and local
// package paths.
const vm = await AgentOs.create({
	// SQLite storage for VM-owned state. On its own it does not make the root
	// filesystem durable; see /agentos/docs/persistence.
	database: { type: "sqlite_file", path: ".agentos/agentos.sqlite" },
	// Store the root filesystem in `database` so files survive VM recreation.
	// Omit it for the default in-memory root, discarded on dispose().
	rootFilesystem: {
		type: "native",
		plugin: { id: "chunked_sqlite", config: {} },
	},
	// 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")],
	// Kernel permission policy (see /agentos/docs/permissions) and runtime caps.
	permissions: { network: "allow" },
	limits: { jsRuntime: { v8HeapLimitMb: 128 } },
	// Install a packed .aospkg from a trusted local path at boot.
	software: [{ packagePath: "/path/to/tool.aospkg" }],
	// 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" },
});

await vm.dispose();