Spin up an agent VM, open sessions against it, and drive them end to end: send prompts, stream responses, switch models, and tear sessions down. Reach for this when you need full lifecycle control over an agent rather than a one-shot prompt.
How it works
The server registers an agent VM with agentOS({ software: [pi] }) and exposes it through a typed RivetKit setup registry. The client connects with createClient and grabs a VM handle with getOrCreate. From that handle, openSession creates or restores a durable session using options such as env, cwd, mcpServers, and additionalInstructions; prompt and cancelPrompt drive turns. A connect() connection surfaces live sessionEvent, vmBooted, and vmShutdown events. Completed ACP updates are retained in SQLite and can be recovered with readHistory; streaming deltas remain ephemeral. Use getSession and listSessions without starting an adapter, getSessionConfig and setSessionConfigOption for adapter-defined controls, unloadSession to release only the runtime, and deleteSession to permanently remove a session and its history.
Run it
npm install
ANTHROPIC_API_KEY=sk-... npx tsx server.ts # start the registry
# in another shell: drive the client functions
ANTHROPIC_API_KEY=sk-... npx tsx client.tsThe server boots the agent VM and the client opens sessions, streams events, and prints session IDs and responses.
Source
View the source on GitHub: https://github.com/rivet-dev/agent-os/tree/main/examples/sessions