agentOS is a lightweight Linux-compatible VM runtime for isolated filesystem, process, terminal, language, and networking workloads.
It ships in two forms:
- a fixed Rust Rivet actor named
agentOS, accessed through a generated TypeScript contract; @rivet-dev/agentos, the embedded TypeScript API for trusted Node.js applications.
The actor is a thin lifecycle and transport wrapper around Core. It does not contain a configurable TypeScript actor implementation.
npm install @rivet-dev/agentos rivetkitimport { createAgentOsClient } from "@rivet-dev/agentos";
const client = createAgentOsClient();
const vm = client.agentOS.getOrCreate(["workspaces", "demo"], {
createWithInput: {
config: {
filesystem: {
root: { type: "durable", namespace: "root" },
},
},
},
});
await vm.filesystem.writeFile({
path: "/home/agentos/hello.txt",
content: "hello\n",
});
const result = await vm.process.run({
command: "cat",
args: ["/home/agentos/hello.txt"],
options: { env: {}, captureStdio: true },
});
console.log(result.stdout);Creation config is used only when the actor is first created. Read the complete
normalized config with config.get; replace it with config.set. Replacement
is whole-object normalization, so omitted properties return to their defaults.
Hosted actions are grouped under:
configandvmfilesystemprocessandterminalcontexts,javascript,typescript, andpythonnetwork.fetch,network.fetchStream,network.connect, andnetwork.previewsoftwarecron
Embedded Core also exposes configurePermissions (Rust: configure_permissions)
for trusted owners to replace a VM permission policy; see the permissions guide.
The hosted actor accepts only serializable, whitelisted filesystem descriptors. It never accepts host mounts, host paths, JavaScript VFS objects, callbacks, or host functions.
Software is an immutable v2 .aospkg artifact. Hosted actors install HTTPS
URLs:
await vm.software.install({
source: {
url: "https://packages.example.com/ripgrep.aospkg",
digest: "sha256:<64 lowercase hex characters>",
},
});The process-wide cache is content-addressed by digest. Release tooling uploads the catalog to S3-compatible object storage and emits a manifest of relative artifact URLs, digests, and sizes. Runtime software is not resolved from npm.
npm install @rivet-dev/agentosimport { AgentOs } from "@rivet-dev/agentos";
const vm = await AgentOs.create();
try {
await vm.filesystem.writeFile("/tmp/hello.txt", "hello\n");
const result = await vm.process.exec("cat /tmp/hello.txt", {
output: { capture: "all" },
});
console.log(result.stdout);
} finally {
await vm.dispose();
}Embedded Core additionally supports trusted local .aospkg paths, host-backed
mount plugins, external VM providers, and host functions. Those capabilities stay
inside the embedding process and are intentionally absent from the hosted actor.
Standalone WASM commands use V8 by default. Embedded callers can select
wasmBackend: "wasmtime" when their sidecar includes the Wasmtime executor;
JavaScript continues to use V8. See the embedded API.
pnpm install --frozen-lockfile
pnpm build
pnpm check-types
cargo check --workspaceRebuild the complete command catalog and stage the local object-store release layout with:
just tools-rebuild
just software-artifacts-dry-runPublic documentation is published from the docs bundle.