zopu-code/.agents/skills/ai-agent-workspace/reference/agent-os/quickstart.md

Quickstart

Source: src/content/docs/agent-os/quickstart.mdx Canonical URL: https://rivet.dev/docs/agent-os/quickstart Description: 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.

Source doc path: /docs/agent-os/quickstart