Quickstart
Run your first agent: Pi in a Rivet Actor, with its tools in a sandbox.
An agent is a Rivet Actor in your backend. Its file and shell tools run in a sandbox, and clients prompt it like any other Actor.
Install
npm add @rivet-dev/pi rivetkit
Define the Actor
import { pi } from "@rivet-dev/pi";
import { setup } from "rivetkit";
const agent = pi({ model: "anthropic/claude-opus-5-5" });
export const registry = setup({
use: { agent },
});
registry.start();
Set ANTHROPIC_API_KEY. For another provider, change model and set its key instead, such as OPENAI_API_KEY, XAI_API_KEY, or OPENROUTER_API_KEY. See LLM API Keys.
Add a sandbox
Pi’s file and shell tools run in a sandbox. Without one they are disabled.
# E2B
npm add @rivet-dev/sandbox-adapter e2b
# Daytona
npm add @rivet-dev/sandbox-adapter @daytonaio/sdk
import { pi } from "@rivet-dev/pi";
import { e2bProvider } from "@rivet-dev/sandbox-adapter/e2b";
import { setup } from "rivetkit";
const agent = pi({
model: "anthropic/claude-opus-5-5",
sandbox: e2bProvider(),
});
export const registry = setup({ use: { agent } });
registry.start();
import { pi } from "@rivet-dev/pi";
import { daytonaProvider } from "@rivet-dev/sandbox-adapter/daytona";
import { setup } from "rivetkit";
const agent = pi({
model: "anthropic/claude-opus-5-5",
sandbox: daytonaProvider(),
});
export const registry = setup({ use: { agent } });
registry.start();
Set E2B_API_KEY for E2B or DAYTONA_API_KEY for Daytona. To write your own provider, see Sandboxes.
Send a prompt
TypeScript
import { createClient } from "rivetkit/client";
import type { registry } from "./server";
const client = createClient<typeof registry>();
const agent = client.agent.getOrCreate(["user-123"]);
const conn = agent.connect();
await conn.prompt("Write a Python script that prints the first 20 prime numbers, run it, and show me the output.");
console.log(await conn.getLastAssistantText());
await conn.dispose();
curl
URL="http://localhost:6420/gateway/agent/action"
AGENT="rvt-namespace=default&rvt-method=getOrCreate&rvt-key=user-123&rvt-pool=default"
curl -X POST "$URL/prompt?$AGENT" \
-H "Content-Type: application/json" \
-d '{"args": ["Write a Python script that prints the first 20 prime numbers, run it, and show me the output."]}'
curl -X POST "$URL/getLastAssistantText?$AGENT" \
-H "Content-Type: application/json" \
-d '{"args": []}'
Each action is a POST to the gateway with its arguments in args. See Call Action.
The prompt action waits for Pi to finish, then getLastAssistantText reads the full reply.
Deploy
By default, Rivet stores Actor state on the local file system.
To scale Rivet in production, pick how much of it you want to run yourself:
Fully managed
Bring your own compute
Full self-hosting
If you are running your own workers, follow the guide for your hosting provider:
Next: Design Patterns, how to structure an app with many agents.