docs(agentos): add embedded quickstart

README.md

@@ -106,7 +106,7 @@ const result = await handle.exec("cat /out.txt");
 console.log(result.stdout); // "hi"
 ```
 
-`@rivet-dev/agentos` runs each VM as a Rivet Actor with built-in persistence, sleep/wake, multiplayer, preview URLs, and orchestration. For direct in-process VM control without the actor runtime, use [`@rivet-dev/agentos-core`](https://agentos-sdk.dev/docs/core) standalone: `AgentOs.create()` boots a VM and returns a handle you call directly.
+`@rivet-dev/agentos` runs each VM as a Rivet Actor with built-in persistence, sleep/wake, multiplayer, preview URLs, and orchestration. To embed VM control in an existing Node.js application without the actor runtime, use [`@rivet-dev/agentos-core`](https://agentos-sdk.dev/docs/quickstart-embedded): `AgentOs.create()` boots a VM and returns a handle you call directly.
 
 See the [Quickstart guide](https://agentos-sdk.dev/docs/quickstart) for the full walkthrough. agentOS is in preview and the API is subject to change — questions and issues welcome on [Discord](https://rivet.dev/discord).
 

docs-internal/design/execution-api-redesign.md

@@ -382,7 +382,7 @@ There is no `vm.executions.*` after this change.
 - `website/src/content/docs/docs/javascript.mdx`
 - `website/src/content/docs/docs/python.mdx`
 - `docs/features/typescript.mdx`
-- `website/src/content/docs/docs/core.mdx`
+- `website/src/content/docs/docs/embedded.mdx`
 - Add a "Contexts" section; retarget the TS namespace; replace all `executionId`
   / `createIfMissing` / `detached` call sites with `createContext` / `contextId`
   / `spawn`. Validate with `pnpm --dir website build`.

docs/CLAUDE.md

@@ -105,6 +105,9 @@ Applies to everything published on the website.
   periods instead.
 - Do not document deltas. A reader who never saw the old version gains nothing
   from "this was renamed".
+- Every agentOS docs page ends with a concise `## Embedded API` section. Prefer
+  checked `<CodeSnippet>` examples over prose. End with: `Read more in the
+  [embedded API quickstart](/agentos/docs/quickstart-embedded).`
 
 ## Previewing locally
 

docs/content/docs/agent-to-agent.mdx

@@ -35,3 +35,12 @@ Bindings are the natural communication layer between agents because:
 
 - Each agent has its own isolated VM and filesystem (they share no filesystem). Pass file contents through the binding input, then use `writeFile` in the binding to land them in the other VM.
 - Use [Workflows](/agentos/docs/workflows) to make multi-agent pipelines durable across restarts.
+
+## Embedded API
+
+Create one `AgentOs` handle per agent and call the reviewer from a host binding.
+Your application owns both handles and their lifecycle.
+
+<CodeSnippet file="examples/embedded/agent-to-agent.ts" title="agent-to-agent.ts" />
+
+Read more in the [embedded API quickstart](/agentos/docs/quickstart-embedded).

docs/content/docs/approvals.mdx

@@ -39,3 +39,12 @@ For a fully automated session, omit `permissionPolicy` or choose `allow_all` exp
 <CodeSnippet file="examples/approvals/auto-approve-client.ts" />
 
 For unattended fail-closed work, choose `reject_all` explicitly. ACP approval is advisory; VM filesystem, network, and process permissions remain the security boundary. Automatically handled requests are neither emitted nor persisted.
+
+## Embedded API
+
+Approval requests arrive through the embedded VM's process-local
+`onSessionEvent()` callback.
+
+<CodeSnippet file="examples/embedded/hooks.ts" title="hooks.ts" />
+
+Read more in the [embedded API quickstart](/agentos/docs/quickstart-embedded).

docs/content/docs/architecture.mdx

@@ -307,7 +307,7 @@ An agent (such as [Pi](https://github.com/mariozechner/pi-coding-agent)) is just
 
 ## Orchestration (Rivet Actors)
 
-The `agentOS()` actor (from `@rivet-dev/agentos`) wraps the raw VM in a [Rivet Actor](/agentos/docs/core), which adds durable state, scheduling, and orchestration. This is what gives you persistence, cron, and workflows out of the box. It also registers the [inspector](/agentos/docs/inspector) tabs in the Rivet dashboard, so every actor comes with a live view of its transcript, filesystem, and processes.
+The `agentOS()` actor (from `@rivet-dev/agentos`) wraps the raw VM in a [Rivet Actor](/actors/docs/), which adds durable state, scheduling, and orchestration. This is what gives you persistence, cron, and workflows out of the box. It also registers inspector tabs in the Rivet dashboard, so every actor comes with a live view of its transcript, filesystem, and processes.
 
 <svg viewBox="0 0 700 200" role="img" aria-label="A Rivet Actor wraps an agentOS VM and adds durable state, cron scheduling, workflows, and sleep/wake persistence." style="width:100%;height:auto;max-width:680px;display:block;margin:1.5rem auto 0.5rem;">
   <rect x="40" y="20" width="620" height="160" rx="14" fill="#faf8f3" stroke="#1b1916" stroke-width="1.5" />

docs/content/docs/authentication.mdx

@@ -22,3 +22,12 @@ The server declares the credential shape and validates it in `onBeforeConnect` (
 </CodeGroup>
 
 See [Actor Authentication](/actors/docs/authentication) for JWT validation, role-based access control, external auth providers, and token caching.
+
+## Embedded API
+
+This layer requires Rivet Actors. An [embedded](/agentos/docs/embedded) VM has no connections, no `params`, and no `onBeforeConnect`, so `AgentOs.create()` authenticates nobody. Your application authenticates its own callers before it touches the VM handle, and decides which caller may reach which VM.
+
+Session credentials still work through `vm.sessions.open()`; see
+[Models & Credentials](/agentos/docs/models-and-credentials#embedded-api).
+
+Read more in the [embedded API quickstart](/agentos/docs/quickstart-embedded).

docs/content/docs/bash.mdx

@@ -49,3 +49,10 @@ Every command inherits the VM [permission policy](/agentos/docs/permissions) and
 [resource limits](/agentos/docs/resource-limits).
 
 <CodeSnippet file="examples/quickstart/bash/limits.ts" />
+
+## Embedded API
+
+The examples above already use `AgentOs.create()`. The host owns `dispose()`,
+and filesystem state only outlives the VM when you configure `database`.
+
+Read more in the [embedded API quickstart](/agentos/docs/quickstart-embedded).

docs/content/docs/bindings.mdx

@@ -89,3 +89,12 @@ Use bindings when you want to expose your own JavaScript functions to agents. Us
 Binding calls from the agent securely invoke your `execute()` functions on the host. Your functions run with full access to the host environment, so you can call databases, APIs, and services directly without proxying credentials into the VM. The agent never sees the credentials, it only sees the binding's input/output contract.
 
 Bindings run on the host with full access to the host environment, so do not expose bindings that could compromise the host without appropriate safeguards.
+
+## Embedded API
+
+Pass the same binding groups to `AgentOs.create()`. The binding contract and
+generated VM commands are unchanged.
+
+<CodeSnippet file="examples/embedded/bindings.ts" title="bindings.ts" />
+
+Read more in the [embedded API quickstart](/agentos/docs/quickstart-embedded).

docs/content/docs/browser.mdx

@@ -67,3 +67,12 @@ browse cloud projects list               # list Browserbase projects
 <Note>
 The [interactive driver mode](https://docs.browserbase.com/integrations/skills/browse-cli) (`browse open`, `browse click`, …) is not supported inside the VM yet ([#1631](https://github.com/rivet-dev/agentos/issues/1631)). For interactive automation, run `browse` inside an external sandbox via [External Sandboxes](/agentos/docs/sandboxes).
 </Note>
+
+## Embedded API
+
+Install the same Browserbase software package and pass its credentials through
+the embedded session environment.
+
+<CodeSnippet file="examples/browserbase/embedded.ts" title="embedded.ts" />
+
+Read more in the [embedded API quickstart](/agentos/docs/quickstart-embedded).