General

Quickstart

Set up an agentOS actor, create a session, and run your first coding agent.

agentOS is in preview and the API is subject to change. If you run into issues, please report them on GitHub or join our Discord.

Install

rivetkit — Actor framework with built-in persistence and orchestration
@rivet-dev/agent-os-common — Standard VM software (curl, grep, git, and more)
@rivet-dev/agent-os-pi — Pi coding agent (Claude Code, Amp, and OpenCode coming soon)

npm install rivetkit @rivet-dev/agent-os-common @rivet-dev/agent-os-pi

Create the Server & Client

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

import { createClient } from "rivetkit/client";
import type { registry } from "./server";

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

// Subscribe to streaming events
agent.on("sessionEvent", (data) => {
  console.log(data.event);
});

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

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

Run

Start the server:

npx tsx server.ts

Then in a separate terminal, 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
Tools — Expose your JavaScript functions to agents as CLI commands
Filesystem — Read, write, and manage files inside the VM
Registry — Browse more agents, tools, and filesystems

agentOS Core

The quickstart above uses rivetkit/agent-os, 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/agent-os-core) standalone.

See agentOS core documentation for reference.