Skip to main content
Sign In
More

Embedded VMs

Embed agentOS Core in a trusted Node.js application.

@rivet-dev/agentos-core runs agentOS VMs inside your Node.js process. Your application owns VM identity, persistence, and disposal. Its native sidecar and platform package must match the installed agentOS version. If resolution reports a missing or mismatched binary, reinstall the packages; AGENTOS_SIDECAR_BIN can select a custom local build.

// Minimal agentOS example: create a VM, write a file, read it back.

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

const vm = await AgentOs.create();

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

await vm.dispose();

Trusted host capabilities

Because the embedding process is trusted, Core accepts values that run in or read from the host:

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();

Sidecar placement

VMs share a pooled sidecar process by default. Create a dedicated sidecar with AgentOs.createSidecar() and pass it as sidecar: { kind: "explicit", handle } to isolate a group of VMs or configure process-wide limits.

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

// An embedded application can use one dedicated sidecar process for 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
Edit this page