Reference

Self-Hosting (Hosted)

Run hosted agentOS VMs on your own infrastructure with Rivet Services.

Self-hosting runs the hosted agentOS API on your own infrastructure instead of Rivet Cloud. It needs two processes: the Rivet control plane, and Rivet Services, which runs the agentOS actor and its VMs. If you only need VMs inside your own Node.js process, use the library instead; it needs neither.

Which one should I use?

	Hosted	Library
Runs	As a durable instance on Rivet Cloud or a self-hosted Docker image	Embedded inside your process as a library
Lifecycle	Durable, sleeps when idle unless a process is running; see actor lifecycle	Ephemeral, runs until `dispose()` or process exit
Package	`@rivet-dev/agentos`, or plain HTTP	`@rivet-dev/agentos-core`
VM identity	A durable VM you create by key and reach by ID	A handle your process owns until `dispose()`
Configuration	Stored with the VM and versioned	Passed to `AgentOs.create()`
Clients	Your backend, or browsers with a scoped JWT	Your backend
Host access	None	Host functions, host mounts, external sandboxes
Previews	Expiring preview URLs	None
Best for	Long-lived VMs shared across clients	Embedding VMs in an existing backend

Run it

Hosted agentOS runs on Rivet Services, the prebuilt node that hosts Rivet’s own Actors. Follow that page to run the control plane and Services, then point your client at your control plane.

Set RIVET_TOKEN to your Rivet token, then create a VM by ID on your control plane from TypeScript or plain HTTP:

// npm install @rivet-dev/agentos
import { createAgentOsClient } from "@rivet-dev/agentos";

const client = createAgentOsClient({ endpoint: "http://localhost:6420" });

const vm = client.agentOS.getOrCreate(["my-vm"]);

curl -X PUT "http://localhost:6420/actors?namespace=default" \
  -H "Authorization: Bearer $RIVET_TOKEN" \
  --json '{
    "name": "agentOS",
    "key": "my-vm",
    "pool": "services",
    "crash_policy": "sleep"
  }'
# → { "actor": { "actor_id": "…" }, "created": true }

Everything in the hosted quickstart and the Hosted HTTP API works the same way. Use http://localhost:6420, or wherever your control plane is reachable, as the base URL instead of https://api.rivet.dev.