docs(agentos): add embedded quickstart

Author: NathanFlurry

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/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 the [inspector](/agentos/docs/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/crash-course.mdx

@@ -1,15 +1,19 @@
 ---
-title: "Direct VM API"
-description: "Use the direct agentOS VM API to create and control isolated execution environments, or compose it inside a Rivet Actor."
+title: "Embedded VMs"
+description: "Reference for embedding agentOS VMs in an existing Node.js application without Rivet Actors."
 skill: true
 ---
 
-`@rivet-dev/agentos` ships both the direct `AgentOs` VM API and the `agentOS()`
-actor API.
+Use the embedded API when you already have a Node.js application and want to
+control agentOS VMs directly. You manage VM identity, persistence, and lifecycle
+yourself instead of using Rivet Actors.
 
-## Direct VM vs actor
+To create your first embedded VM, start with the
+[embedded quickstart](/agentos/docs/quickstart-embedded).
 
-| | Direct VM | Actor |
+## Embedded API vs actor
+
+| | Embedded API | Actor |
 |-|---|---|
 | Persistence | In-memory by default (pluggable via [mounts](#mounts)) | Persistent filesystem and sessions |
 | Distributed state | Manage yourself | Built-in |
@@ -24,29 +28,16 @@ actor API.
 
 - Use [Rivet Actors](/actors/docs/) for persistence,
   networking, and orchestration.
-- Use `AgentOs.create()` for direct VM control in a Node.js process.
-- `agentOS()` returns an ordinary TypeScript Rivet actor definition — VM options
+- Use `AgentOs.create()` to embed VM control in a Node.js application.
+- `agentOS()` returns an ordinary TypeScript Rivet actor definition: VM options
   plus normal actor state, actions, events, queues, connection types, and
   lifecycle hooks (`onBeforeConnect`).
-- AgentOS actions/events merge in automatically; their names are reserved.
-- The VM is created lazily on the first AgentOS action after wake, disposed on
-  sleep — so a connection can subscribe before `vmBooted`.
+- agentOS actions/events merge in automatically; their names are reserved.
+- The VM is created lazily on the first agentOS action after wake, disposed on
+  sleep, so a connection can subscribe before `vmBooted`.
 - Creation input flows through `client.vm.create("key", { input })` and reaches
   `createState(c, input)` and `onCreate(c, input)`.
 
-## Install
-
-```bash
-npm install @rivet-dev/agentos
-```
-
-## Boot a VM
-
-`AgentOs.create()` boots the VM in-process and returns a handle you call
-directly — no actor runtime, no client/server split.
-
-<CodeSnippet file="examples/core/vm.ts" region="boot" title="vm.ts" />
-
 ## Sidecar process
 
 - Every VM runs inside a **shared sidecar process**, not its own process.
@@ -57,14 +48,14 @@ directly — no actor runtime, no client/server split.
 - Automatic for `agentOS()`, `AgentOs.create()`, and Rivet Actors.
 - Disposing a VM tears down only that VM; the sidecar is reused for the host
   process lifetime.
-- Advanced: the direct VM API exposes explicit sidecar handles to isolate a
+- Advanced: the embedded API exposes explicit sidecar handles to isolate a
   group of VMs in their own process.
 
-<CodeSnippet file="examples/core/advanced.ts" title="advanced.ts" />
+<CodeSnippet file="examples/embedded/advanced.ts" title="advanced.ts" />
 
 ## Filesystem
 
-<CodeSnippet file="examples/core/vm.ts" region="filesystem" title="vm.ts" />
+<CodeSnippet file="examples/embedded/vm.ts" region="filesystem" title="vm.ts" />
 
 ## Contexts
 
@@ -73,7 +64,7 @@ Create one explicitly, then pass its `contextId`; unknown IDs fail instead of
 silently creating fresh state. A context pins to the first inline language used,
 although JavaScript and TypeScript intentionally share one isolate.
 
-<CodeSnippet file="examples/core/vm.ts" region="contexts" title="vm.ts" />
+<CodeSnippet file="examples/embedded/vm.ts" region="contexts" title="vm.ts" />
 
 Contexts live for the VM lifetime. In an actor, sleep disposes the VM and its
 contexts, so create a context lazily on the first stateful action after wake
@@ -82,10 +73,10 @@ instead of persisting and blindly reusing its ID.
 ## Processes
 
 - `process.spawn()` and language `spawn` methods return a numeric `pid`.
-- `onProcessOutput(pid, …)` — unified stdout/stderr stream.
-- `onProcessExit(pid, …)` — completion.
+- `onProcessOutput(pid, …)`: unified stdout/stderr stream.
+- `onProcessExit(pid, …)`: completion.
 
-<CodeSnippet file="examples/core/vm.ts" region="processes" title="vm.ts" />
+<CodeSnippet file="examples/embedded/vm.ts" region="processes" title="vm.ts" />
 
 ## Agent sessions
 
@@ -97,54 +88,54 @@ instead of persisting and blindly reusing its ID.
 - Durable entries recover via `readHistory`; ephemeral agent/thought deltas do
   not.
 
-<CodeSnippet file="examples/core/vm.ts" region="sessions" title="vm.ts" />
+<CodeSnippet file="examples/embedded/vm.ts" region="sessions" title="vm.ts" />
 
 ## Networking
 
 `httpRequest({ port, path, ... })` reaches a server inside the VM and returns a
 bounded, serializable response DTO.
 
-<CodeSnippet file="examples/core/vm.ts" region="networking" title="vm.ts" />
+<CodeSnippet file="examples/embedded/vm.ts" region="networking" title="vm.ts" />
 
 ## Cron jobs
 
 - Run an `"exec"` command or a `"session"` prompt on a schedule.
 - Fired jobs surface through `onCronEvent`.
 
-<CodeSnippet file="examples/core/vm.ts" region="cron" title="vm.ts" />
+<CodeSnippet file="examples/embedded/vm.ts" region="cron" title="vm.ts" />
 
 ## Mounts
 
 - Configure filesystem backends at boot.
 - Native mount plugins (host directories, S3, etc.) are passed via `plugin`,
   each with an `id` and a `config`.
 
-<CodeSnippet file="examples/core/mounts.ts" title="mounts.ts" />
+<CodeSnippet file="examples/embedded/mounts.ts" title="mounts.ts" />
 
 ## Configuration reference
 
 - All VM config is a single flat object passed to `AgentOs.create()`.
 - The [`agentOS()` actor](/agentos/docs/quickstart) accepts the same options and layers
   persistence, sleep/wake, and preview URLs on top.
 
-<CodeSnippet file="examples/core/config-reference.ts" title="config-reference.ts" />
+<CodeSnippet file="examples/embedded/config-reference.ts" title="config-reference.ts" />
 
 See [Mounts](#mounts) and [Software](/agentos/docs/software).
 
 ### Session events
 
 - `onSessionEvent` receives a union of exact native ACP `SessionUpdate`,
   `RequestPermissionRequest`, and `RequestPermissionResponse` payloads wrapped
-  with AgentOS durability metadata.
+  with agentOS durability metadata.
 - Register before prompting.
 - On reconnect, read durable history after your last sequence and dedup by
   `(sessionId, sequence)`.
 
-<CodeSnippet file="examples/core/hooks.ts" title="hooks.ts" />
+<CodeSnippet file="examples/embedded/hooks.ts" title="hooks.ts" />
 
 ### Timeouts and sleep
 
 - Action timeouts and automatic sleep/wake are [`agentOS()` actor](/agentos/docs/quickstart)
-  features, not the direct VM API.
-- A direct VM stays alive until `dispose()`. See
+  features, not the embedded API.
+- A VM created through the embedded API stays alive until `dispose()`. See
   [Persistence & Sleep](/agentos/docs/persistence).

docs/content/docs/core.mdx docs/content/docs/embedded.mdxdocs/content/docs/core.mdx renamed to docs/content/docs/embedded.mdx

@@ -62,7 +62,7 @@ The actor's durable root is handled separately: the sidecar connects directly to
 
 ## File operations
 
-These operations are primarily what the agent uses inside the VM, and are also available from the client to seed inputs and read results. For large or read-only inputs (a repo, a dataset), a read-only [host mount](#mounts) is faster than copying files in. Programs that need stdin or live output use exec instead (see the [Direct VM API](/agentos/docs/core)).
+These operations are primarily what the agent uses inside the VM, and are also available from the client to seed inputs and read results. For large or read-only inputs (a repo, a dataset), a read-only [host mount](#mounts) is faster than copying files in. Programs that need stdin or live output use exec instead (see the [embedded API](/agentos/docs/embedded)).
 
 ### Read and write
 

docs/content/docs/filesystem.mdx

@@ -11,8 +11,8 @@ and orchestration built in.
   <Card title="Quickstart" href="/agentos/docs/quickstart">
     Boot a VM and run your first coding agent.
   </Card>
-  <Card title="Crash Course" href="/agentos/docs/crash-course">
-    Learn the core agentOS concepts.
+  <Card title="Quickstart (Embedded)" href="/agentos/docs/quickstart-embedded">
+    Run agentOS directly inside an existing Node.js application.
   </Card>
   <Card title="Agents" href="/agentos/docs/agents/pi">
     Run Pi, Claude Code, Codex, and OpenCode.