Prefer to read code? Clone the example repository.View on GitHub
1. **Install**
- **@rivet-dev/agentos** — Actor framework with built-in persistence and orchestration
- **@agentos-software/pi** — [Pi](https://github.com/mariozechner/pi-coding-agent) coding agent. [Claude Code](/agentos/docs/agents/claude), [Codex](/agentos/docs/agents/codex), and [OpenCode](/agentos/docs/agents/opencode) install the same way.
```bash
npm install @rivet-dev/agentos @agentos-software/pi
```
2. **Create the server**
examples/quickstart-app/server.ts:
```ts
import { agentOS, setup } from "@rivet-dev/agentos";
import pi from "@agentos-software/pi";
const vm = agentOS({
software: [pi],
});
export const registry = setup({ use: { vm } });
registry.start();
```
3. **Create the client**
The client can be any public frontend or another backend. The same `vm` actor is reachable from a plain Node script, a browser/React app, or a separate server.
examples/quickstart-app/client.ts:
```ts
import { createClient } from "@rivet-dev/agentos/client";
import type { registry } from "./server";
const client = createClient({
endpoint: "http://localhost:6420",
});
const handle = client.vm.getOrCreate("my-agent");
// Subscribe to streaming events. The payload is inferred from the event schema.
const conn = handle.connect();
conn.on("sessionEvent", (event) => {
console.log(event);
});
// Open a durable session and send a prompt.
await handle.sessions.open({
agent: "pi",
env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
});
await handle.sessions.prompt({
content: [
{ type: "text", text: "Write a hello world script to /workspace/hello.js" },
],
});
// Read the file the agent created
const content = await handle.filesystem.readFile("/workspace/hello.js");
console.log(new TextDecoder().decode(content));
```
examples/quickstart-app/Agent.tsx:
```tsx
import { createRivetKit } from "@rivet-dev/agentos/react";
import { useState } from "react";
import type { registry } from "./server";
const { useActor } = createRivetKit("http://localhost:6420");
export function Agent() {
const [log, setLog] = useState("");
const agent = useActor({ name: "vm", key: "my-agent" });
// Stream agent events into component state
agent.useEvent("sessionEvent", (event) => {
setLog((prev) => prev + JSON.stringify(event) + "\n");
});
async function run() {
// In production, inject credentials on the server (see /docs/models-and-credentials)
const connection = agent.connection;
if (!connection) return;
await connection.sessions.open({
agent: "pi",
env: { ANTHROPIC_API_KEY: process.env.VITE_ANTHROPIC_API_KEY! },
});
await connection.sessions.prompt({
content: [
{
type: "text",
text: "Write a hello world script to /workspace/hello.js",
},
],
});
}
return (
{log}
);
}
```
4. **Run it**
Start the server, then run the client in a second terminal:
```bash
# Terminal 1: start the server
npx tsx server.ts
# Terminal 2: run the client
npx tsx client.ts
```
With the server running, open http://localhost:6420/ui to watch the VM in the [inspector](/agentos/docs/inspector): the live transcript, the filesystem, and its processes.
5. **Customize**
Now that you have a working agent, customize it to fit your needs:
- **[Software](/agentos/docs/software)** — Install software packages inside the VM
- **[Filesystem](/agentos/docs/filesystem)** — Read, write, and manage files inside the VM
- **[Permissions & Resource Limits](/agentos/docs/permissions)** — Gate what the agent can do and cap its resource usage
- **[Bindings](/agentos/docs/bindings)** — Expose your JavaScript functions to agents as CLI commands
5. **Deploy**
By default, agentOS runs locally with `npx rivetkit dev` — no infrastructure needed. To run in production, deploy to any of these targets:
> **NOTE:** agentOS is in preview and the API is subject to change. If you run into issues, please [report them on GitHub](https://github.com/rivet-dev/rivet/issues) or [join our Discord](https://rivet.dev/discord).
## Direct VM API
The same `@rivet-dev/agentos` package also exports `AgentOs.create()` for direct
VM control without the actor lifecycle, multiplayer, or orchestration layer.
See the [direct VM API documentation](/agentos/docs/core) for reference.