# Rivet

Rivet is agentOS's native framework. The `agentOS()` function returns an ordinary [Rivet Actor](https://rivet.dev/docs/actors), so each agentOS VM is a directly addressable actor with its own durable filesystem, state, and session history—no adapter layer required.

[View the complete example →](https://github.com/rivet-dev/agentos/tree/main/examples/quickstart-app)

## Quickstart

### Create a project

```sh
mkdir my-agent && cd my-agent
npm init -y
npm pkg set type=module
npm add @rivet-dev/agentos @agentos-software/pi
npm add --save-dev tsx typescript
```

### Create an agentOS actor

Create `server.ts`. The `agentOS()` call returns a normal Rivet Actor definition, and `setup()` registers it with the Rivet runtime:

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();
```

### Connect to the actor

Create `client.ts` to address an actor by name, subscribe to its events, open a session, and send a prompt:

client.ts:

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

const client = createClient<typeof registry>({
	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));
```

### Run locally

Start the actor, then run the client in a second terminal with the provider key required by your model:

```sh
# Terminal 1
npx tsx server.ts

# Terminal 2
ANTHROPIC_API_KEY=... npx tsx client.ts
```

### Add orchestration

Because an agentOS VM is a Rivet Actor, you can compose it with Rivet's orchestration primitives:

- **[Durable workflows](/agentos/docs/workflows)** — Run multi-step agent tasks that retry and resume after crashes.
- **[Multiplayer agents](/agentos/docs/multiplayer)** — Stream agent output to multiple connected clients in real time.
- **[Agent-to-agent systems](/agentos/docs/agent-to-agent)** — Connect isolated agents through typed bindings and durable pipelines.
- **[Scheduled agents](/agentos/docs/cron)** — Run commands and agent sessions on timers or cron schedules.
- **[Human-in-the-loop flows](/agentos/docs/approvals)** — Pause for tool approval and resume from durable event history.

### Deploy

Deploy to one of the supported platforms:

## Learn more

See the [agentOS quickstart](/agentos/docs/quickstart) for VM configuration and the [Rivet Actor documentation](https://rivet.dev/docs/actors) for state, actions, events, queues, workflows, and deployment.