Persistence & Sleep

• Persistent filesystem backs /home/user automatically
• Session transcripts persisted with sequence numbers for replay
• Configurable sleep with a 15-minute grace period by default
• Automatic wake 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

Sleep vs destroy

VM boot and shutdown events

Subscribe to vmBooted and vmShutdown events to track VM lifecycle.

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

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

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

```ts @nocheck server.ts
import { agentOs } from "rivetkit/agent-os";
import { setup } from "rivetkit";
import common from "@rivet-dev/agent-os-common";
import pi from "@rivet-dev/agent-os-pi";

const vm = agentOs({
  options: { software: [common, pi] },
});

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

Resuming after sleep

When the actor wakes up:

1. The VM boots and the filesystem is restored from SQLite
2. Session records and event history are available immediately
3. Processes and shells from the previous session are gone
4. Clients can reconnect and resume sessions using resumeSession
5. Use getSessionEvents to replay missed events

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

// List sessions from before sleep const sessions = await agent.listPersistedSessions(); console.log("Previous sessions:", sessions.length);

// Resume the most recent session if (sessions.length > 0) { const last = sessions[0]; await agent.resumeSession(last.sessionId);

// Replay events for transcript const events = await agent.getSessionEvents(last.sessionId); for (const e of events) { console.log(e.seq, e.event.method); } }

```ts @nocheck server.ts
import { agentOs } from "rivetkit/agent-os";
import { setup } from "rivetkit";
import common from "@rivet-dev/agent-os-common";
import pi from "@rivet-dev/agent-os-pi";

const vm = agentOs({
  options: { software: [common, pi] },
});

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

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.