Persistence & Sleep

How agentOS persists data and manages sleep/wake cycles.

agentOS automatically persists the /home/agentos filesystem and session transcripts (with sequence numbers for replay) across sleep/wake, sleeping after a configurable grace period (15 minutes by default) and waking automatically when a client connects or a cron job triggers.

What persists across sleep

What prevents sleep

The actor stays awake as long as any of these are active:

• Active sessions (created but not closed/destroyed)
• Running processes (spawned but not exited)
• Active shells (opened but not closed)
• Pending hooks (server-side callbacks still executing)

When all activity stops, the sleep grace period begins.

Sleep grace period

After all activity stops, the actor waits 15 minutes before sleeping. This allows for brief pauses between interactions without restarting the VM.

Activity stops ──> 15 min grace period ──> Actor sleeps
                                           (VM shutdown, processes killed)

New client connects ──> Actor wakes ──> VM boots ──> Filesystem restored

Timeouts

These are set internally by the agentOS() factory and cannot be overridden per-call.

Sleep vs destroy

VM boot and shutdown events

Subscribe to vmBooted and vmShutdown events to track VM lifecycle.

import { createClient } from "@rivet-dev/agentos/client";
import type { registry } from "./server";

const client = createClient<typeof registry>({ endpoint: "http://localhost:6420" });

const conn = client.vm.getOrCreate("my-agent").connect();

conn.on("vmBooted", () => {
  console.log("VM is ready");
});

conn.on("vmShutdown", (payload) => {
  console.log("VM shutdown reason:", payload.reason);
  // reason: "sleep" | "destroy" | "error"
});

import { agentOS, setup } from "@rivet-dev/agentos";
// In a real app: import pi from "@agentos-software/pi";
import pi from "./software/pi";

const vm = agentOS({
  software: [pi],
});

export const registry = setup({ use: { vm } });
registry.start();

Resuming after sleep

When the actor wakes up, the VM boots and the filesystem is restored from SQLite, session records and event history are immediately available, and processes and shells from the previous session are gone. Clients can reconnect, list prior work with listPersistedSessions (which works without a running VM), and replay a session’s persisted transcript with getSessionEvents.

import { createClient } from "@rivet-dev/agentos/client";
import type { registry } from "./server";

const client = createClient<typeof registry>({ endpoint: "http://localhost:6420" });
const vm = client.vm.getOrCreate("my-agent");

// List sessions persisted before sleep (works without a running VM)
const sessions = await vm.listPersistedSessions();
console.log("Previous sessions:", sessions.length);

// Replay the most recent session's transcript from durable storage
const last = sessions[0];
if (last) {
  const events = await vm.getSessionEvents(last.sessionId);
  for (const e of events) {
    console.log(e.seq, e.event.method);
  }
}

Persisted tables schema

agent_os_fs_entries

Stores the virtual filesystem.

agent_os_sessions

Stores session metadata.

agent_os_session_events

Stores session event history.