Reference

Self-Hosting (Hosted)

Run hosted agentOS VMs on your own infrastructure with the Rivet control plane and the agentOS worker image.

Self-hosting runs the hosted agentOS API on your own infrastructure instead of Rivet Cloud. It needs two processes: the Rivet control plane, and the agentOS worker that 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

Run the Rivet control plane

The control plane requires an admin token. See Admin token.

export RIVET_ADMIN_TOKEN=$(openssl rand -hex 32)

docker run -p 6420:6420 \
  -e RIVET__AUTH__ADMIN_TOKEN="$RIVET_ADMIN_TOKEN" \
  rivetdev/engine

See the self-hosting guides for other ways to run it.

Register the agentOS worker pool

The agentOS worker connects to a pool named services:

curl -X PUT "http://localhost:6420/runner-configs/services?namespace=default" \
  -H "Authorization: Bearer $RIVET_ADMIN_TOKEN" \
  --json '{"datacenters": {"default": {"normal": {}}}}'

Run the agentOS worker

The worker is what actually runs your VMs. It connects to the control plane:

docker run \
  --add-host=host.docker.internal:host-gateway \
  -e RIVET_ENDPOINT=http://host.docker.internal:6420 \
  -e RIVET_TOKEN="$RIVET_ADMIN_TOKEN" \
  rivetdev/services:0.2.0

Point your client at it

Set RIVET_TOKEN to the admin 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_ADMIN_TOKEN" \
  --json '{
    "name": "agentOS",
    "key": "my-vm",
    "runner_name_selector": "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.