actors CLAUDE.md

CLAUDE.md

Design constraints, invariants, and reference commands for the Rivet monorepo. For implementation details, wiring, and procedural gotchas, follow the links under Reference Docs.

Terminology

Always spell the product name agentOS, never AgentOS; do not alter type identifiers such as AgentOSActorConfig.

ALWAYS use rivet.dev - NEVER use rivet.gg

• API endpoint: https://api.rivet.dev
• Cloud API endpoint: https://cloud-api.rivet.dev
• Dashboard: https://dashboard.rivet.dev
• Documentation: https://rivet.dev/docs

Use "sandbox mounting" when referring to the agentOS sandbox integration. Do not use "sandbox extension" or "sandbox escalation." The feature mounts a sandbox as a filesystem inside the VM.

ALWAYS use github.com/rivet-dev/rivet - NEVER use rivet-dev/rivetkit or rivet-gg/*

Never modify an existing published *.bare runner protocol version unless explicitly asked to do so.

• Add a new versioned schema instead, then migrate versioned.rs and related compatibility code to bridge old versions forward.
• When bumping the protocol version, update PROTOCOL_MK2_VERSION in engine/packages/runner-protocol/src/lib.rs and PROTOCOL_VERSION in rivetkit-typescript/packages/engine-runner/src/mod.ts together. Both must match the latest schema version.

Always use versioned BARE (vbare) instead of raw serde_bare for any persisted or wire-format encoding unless explicitly told otherwise. Raw serde_bare::to_vec / from_slice has no version header, so any future schema change forces hand-rolled LegacyXxx fallback structs. vbare::OwnedVersionedData plus a versioned *.bare schema is the standard pattern. Acceptable raw-bare exceptions: ephemeral in-memory encodings that never cross a process boundary or hit disk, and wire formats whose protocol version is coordinated out-of-band (e.g. an HTTP path like /v{PROTOCOL_VERSION}/... or another channel that pins both peers to one schema per call).