Persistence & Sleep

Persist an agentOS VM's filesystem in SQLite so files survive VM recreation.

By default, a VM’s root filesystem is an in-memory overlay over the bundled base image. Its files are discarded when the VM is replaced or disposed.

To keep files, give a hosted VM a durable root in its config. In the library, give the VM a SQLite database and store its root filesystem there with the chunked_sqlite plugin; a new VM created with the same options sees the same files.

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

const client = createAgentOsClient({ endpoint: "https://api.rivet.dev" });

const vm = client.agentOS.getOrCreate(["my-vm"], {
	createWithInput: {
		config: { filesystem: { root: { type: "durable" } } },
	},
});

await vm.v1.filesystem.writeFile({
	path: "/home/agentos/result.txt",
	content: "persistent",
});

import { mkdirSync } from "node:fs";
import { resolve } from "node:path";
import { AgentOs, type AgentOsOptions } from "@rivet-dev/agentos-core";

mkdirSync(".agentos", { recursive: true });
const options = {
	// The SQLite file that stores the VM's durable state.
	database: {
		type: "sqlite_file",
		path: resolve(".agentos/agentos.sqlite"),
	},
	// Store the root filesystem in that database instead of in memory.
	rootFilesystem: {
		type: "native",
		plugin: { id: "chunked_sqlite", config: {} },
	},
} satisfies AgentOsOptions;

let vm = await AgentOs.create(options);
await vm.filesystem.writeFile("/home/agentos/result.txt", "persistent");
await vm.dispose();

vm = await AgentOs.create(options);
const result = await vm.filesystem.readFile("/home/agentos/result.txt");
console.log(new TextDecoder().decode(result));
await vm.dispose();

In the library, database on its own stores Core and filesystem metadata, but does not make the default in-memory root durable. A SQLite-backed root starts without the bundled base image’s files.

Persisted filesystems survive VM recreation. Running processes, terminals, language contexts, open streams, and live subscriptions do not.

Sleep

A hosted VM sleeps when idle unless a process is running, and reports vm.shutdown with reason "sleep". The VM starts lazily on the first action after wake. Durable files, configuration, and cron jobs survive sleep. See actor lifecycle.

Library durable state uses agentos_core_* tables and filesystem storage uses agentos_fs_*. Each owner has an independent schema version and migration transaction.

In the library, the embedding application owns VM identity and decides when to recreate or dispose the VM.