General

Quickstart

Use this pre-built prompt to get started faster.

Prefer to read code? Clone the example repository.View on GitHub

Install
- @rivet-dev/agentos — Actor framework with built-in persistence and orchestration
- @agentos-software/pi — Pi coding agent (Claude Code, Amp, and OpenCode coming soon)
Terminal window
```
npm install @rivet-dev/agentos @agentos-software/pi
```

Create the server

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

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.

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", (data) => {
  console.log(data.event);
});

// Create a session and send a prompt
const session = await handle.createSession("pi", {
  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
});
await handle.sendPrompt(
  session.sessionId,
  "Write a hello world script to /home/user/hello.js",
);

// Read the file the agent created
const content = await handle.readFile("/home/user/hello.js");
console.log(new TextDecoder().decode(content));

import { createRivetKit } from "@rivet-dev/agentos/react";
import { useState } from "react";
import type { registry } from "./server";

const { useActor } = createRivetKit<typeof registry>("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", (data) => {
    setLog((prev) => prev + JSON.stringify(data.event) + "\n");
  });

  async function run() {
    // In production, inject credentials on the server (see /docs/llm-credentials)
    const session = await agent.connection?.createSession("pi", {
      env: { ANTHROPIC_API_KEY: process.env.VITE_ANTHROPIC_API_KEY! },
    });
    if (!session) return;
    await agent.connection?.sendPrompt(
      session.sessionId,
      "Write a hello world script to /home/user/hello.js",
    );
  }

  return (
    <div>
      <button onClick={run}>Run agent</button>
      <pre>{log}</pre>
    </div>
  );
}

Run it

Start the server, then run the client in a second terminal:

# Terminal 1: start the server
npx tsx server.ts

# Terminal 2: run the client
npx tsx client.ts

Customize

Now that you have a working agent, customize it to fit your needs:
- Software — Install software packages inside the VM
- Filesystem — Read, write, and manage files inside the VM
- Permissions & Resource Limits — Gate what the agent can do and cap its resource usage
- Bindings — Expose your JavaScript functions to agents as CLI commands

agentOS Core

The quickstart above uses @rivet-dev/agentos, which includes statefulness, multiplayer, and orchestration out of the box. If you only need direct VM control without those features, you can use the core package (@rivet-dev/agentos-core) standalone.

See agentOS core documentation for reference.