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 the key for your model provider, such as ANTHROPIC_API_KEY.
Add a sandbox
Pi’s file and shell tools run in a sandbox. Without one they are disabled.
npm add @rivet-dev/sandbox-adapter
import { pi } from "@rivet-dev/pi";
import { agentOSProvider } from "@rivet-dev/sandbox-adapter/agentos";
import { setup } from "rivetkit";
const agent = pi({
model: "anthropic/claude-opus-5-5",
sandbox: agentOSProvider(),
});
export const registry = setup({ use: { agent } });
registry.start();
To use another provider, install its SDK and pass its provider instead. Provider credentials never enter the sandbox.
| Provider | Import from @rivet-dev/sandbox-adapter | SDK |
|---|---|---|
| E2B | e2bProvider from /e2b | e2b |
| Daytona | daytonaProvider from /daytona | @daytonaio/sdk |
The agentOS VM comes with coreutils, which provides sh and the basic commands the agent runs. For another provider, implement SandboxProvider. 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(["support", "customer-123"]);
const conn = agent.connect();
await conn.prompt("Inspect the project and summarize its test failures.");
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=support,customer-123&rvt-pool=default"
curl -X POST "$URL/prompt?$AGENT" \
-H "Content-Type: application/json" \
-d '{"args": ["Inspect the project and summarize its test failures."]}'
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.
prompt 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:
The rest of the Core pages build on this agent.
Next: Session Lifecycle, what happens while the agent answers a prompt.