docs(agentos): sync from rivet-dev/agentos

vendor/agentos/docs/content/docs/agents/claude.mdx

@@ -4,7 +4,7 @@ description: "Run Claude Code inside an agentOS VM with durable sessions, config
 skill: false
 ---
 
-## Quick start
+## Quickstart
 
 <CodeGroup>
 <CodeSnippet file="examples/claude/server.ts" />
@@ -27,6 +27,23 @@ Set the relevant variable(s) on the session's `env`, sourced from your server's
 
 See [Models & Credentials](/agentos/docs/models-and-credentials), and Claude Code's [environment variables](https://code.claude.com/docs/en/env-vars) for the full list.
 
+## System prompt
+
+By default, the agentOS [system prompt](/agentos/docs/system-prompt), including your `additionalInstructions`, is appended to Claude Code's built-in `claude_code` system prompt.
+
+To use only your own system prompt, set `ACP_SYSTEM_PROMPT_MODE=replace` on the session's `env`. The built-in Claude Code prompt is dropped, and Claude receives the assembled agentOS prompt instead. Use `skipOsInstructions: true` with `additionalInstructions` to send only your text.
+
+```ts
+await agent.sessions.open({
+	agent: "claude",
+	env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!, ACP_SYSTEM_PROMPT_MODE: "replace" },
+	skipOsInstructions: true,
+	additionalInstructions: "You are a support assistant for Acme's billing API.",
+});
+```
+
+`ACP_SYSTEM_PROMPT_MODE` accepts `append` (the default) or `replace`. Any other value makes the session fail to start with an error that names the variable. `replace` also needs a non-empty prompt, so don't combine it with `skipOsInstructions` unless you set `additionalInstructions`.
+
 ## Skills
 
 Claude Code discovers [agent skills](https://docs.claude.com/en/docs/claude-code/skills) from `SKILL.md` files under its skills directory. Write the skill into the VM before creating a session and Claude Code loads it automatically.

vendor/agentos/docs/content/docs/agents/codex.mdx

@@ -5,7 +5,7 @@ description: "Run Codex inside an agentOS VM with durable sessions, configurable
 skill: false
 ---
 
-## Quick start
+## Quickstart
 
 <CodeGroup>
 <CodeSnippet file="examples/codex/server.ts" title="server.ts" />

vendor/agentos/docs/content/docs/agents/opencode.mdx

@@ -4,7 +4,7 @@ description: "Run OpenCode inside an agentOS VM with durable sessions, configura
 skill: false
 ---
 
-## Quick start
+## Quickstart
 
 <CodeGroup>
 <CodeSnippet file="examples/opencode/server.ts" />

vendor/agentos/docs/content/docs/agents/pi.mdx

@@ -5,12 +5,12 @@ description: "Run Pi inside an agentOS VM with durable sessions, extensions, cus
 skill: true
 ---
 
-## Quick start
+## Quickstart
 
 <CodeGroup>
 <CodeSnippet file="examples/pi/server.ts" />
 
-<CodeSnippet file="examples/pi/client.ts" region="quick-start" />
+<CodeSnippet file="examples/pi/client.ts" region="quickstart" />
 </CodeGroup>
 
 Read [Sessions](/agentos/docs/sessions) first for session options, streaming events, prompts, and lifecycle management.

vendor/agentos/docs/content/docs/architecture/javascript-executor.mdx

@@ -39,8 +39,9 @@ Guest V8 execution is deliberately different:
   the only non-V8 platform thread that enters that isolate.
 - Synchronous guest JavaScript or a synchronous bridge wait can block that
   executor, but cannot occupy a Tokio worker or another VM's executor.
-- The number of active and warm executor threads is bounded separately from
-  socket and task counts.
+- Operators can cap active executor threads separately from socket and task
+  counts with `runtime.executor.maxActiveVms`. Executor admission is uncapped
+  by default and is not derived from the sidecar's reported CPU count.
 
 There is therefore no "Tokio task running a Node.js process." Trusted I/O runs
 as Tokio tasks; untrusted JavaScript runs on a V8 executor thread.

vendor/agentos/docs/content/docs/bindings.mdx

@@ -4,7 +4,7 @@ description: "Expose trusted host functions to agentOS coding agents as typed CL
 skill: true
 ---
 
-Expose your host JavaScript functions (defined with Zod input schemas) to agents as auto-generated CLI commands installed at `/usr/local/bin/agentos-{name}` inside the VM, injected into the agent's [system prompt](/agentos/docs/system-prompt) and callable inside scripts for code-mode token savings.
+Expose your host JavaScript functions (defined with Zod input schemas) to agents as auto-generated CLI commands installed at `/bin/agentos-{name}` inside the VM, injected into the agent's [system prompt](/agentos/docs/system-prompt) and callable inside scripts for code-mode token savings.
 
 ## Getting started
 
@@ -34,7 +34,7 @@ Optional fields (via `.optional()`) become optional flags. Required fields are e
 
 ### What the agent sees
 
-When bindings are registered, CLI shims are installed at `/usr/local/bin/agentos-{name}` inside the VM and the binding list is injected into the agent's [system prompt](/agentos/docs/system-prompt), so keep binding descriptions concise to save tokens.
+When bindings are registered, CLI shims are installed at `/bin/agentos-{name}` inside the VM and the binding list is injected into the agent's [system prompt](/agentos/docs/system-prompt), so keep binding descriptions concise to save tokens.
 
 The agent interacts with bindings as shell commands:
 

vendor/agentos/docs/content/docs/javascript.mdx

@@ -44,15 +44,21 @@ interpolated into source.
 
 ## Keep state between calls
 
-Pass a `contextId` to keep globals, imports, and modules alive across calls in
-one retained V8 isolate.
+Pass a `contextId` to keep one V8 isolate and its global state alive across
+calls.
 
 <CodeSnippet file="examples/js-sdk-overview/src/contexts.ts" />
 
 A context runs one operation at a time — reusing a busy `contextId` fails
 immediately. Files, npm, Bash, and type checks may pass the same id, but they run
 in fresh processes and never touch retained memory.
 
+JavaScript defaults to `format: "module"`. Each call is a separate root ES
+module, so its imports, top-level declarations, and exports are scoped to that
+call. Put values on `globalThis` when a later call in the same context needs
+them. For REPL-style script semantics where top-level lexical declarations stay
+visible, pass `format: "commonjs"` consistently for that context.
+
 Create the context explicitly before use; an unknown id fails instead of silently
 starting fresh state. A context pins to the first inline language that used it,
 though JavaScript and TypeScript intentionally share one isolate.

vendor/agentos/docs/content/docs/resource-limits.mdx

@@ -15,6 +15,11 @@ Every agentOS VM runs with **per-VM resource and runtime caps**. These caps cont
 
 Set caps on the `limits` object in the `agentOS` config. Limits are grouped by subsystem (`resources`, `process`, `jsRuntime`, `python`, `wasm`, and more). Omitted limits keep their secure default.
 
+V8 executor admission is process-wide rather than per-VM. It is uncapped by
+default and does not derive a ceiling from the sidecar's reported CPU count.
+Operators can set `runtime.executor.maxActiveVms` when creating a sidecar to
+enforce an explicit concurrent-executor ceiling.
+
 <CodeSnippet file="examples/resource-limits/server.ts" />
 
 ## Available caps
@@ -23,7 +28,7 @@ Set caps on the `limits` object in the `agentOS` config. Limits are grouped by s
 |---|---|---|
 | `resources.maxProcesses` | Concurrent processes in the VM process table | Caps fork bombs and runaway spawning. New spawns fail with `EAGAIN`. |
 | `resources.maxOpenFds` | Open file descriptors | Exhausting the table fails with `EMFILE` / `ENFILE`. |
-| `resources.maxSockets` | Open sockets in the socket table | Bounds concurrent connections; excess `connect`/`accept` fail. |
+| `resources.maxSockets` | Open sockets in the socket table | Default is `256`. This includes guest sockets and the sidecar-owned sockets used to send host requests into VM services. Excess socket operations fail instead of consuming more host resources. |
 | `resources.maxFilesystemBytes` | Total bytes stored in the virtual filesystem | Bounds VFS storage; writes past the budget fail with a no-space error. |
 | `resources.maxInodeCount` | Inodes retained by the virtual filesystem | Default is `16384`; creating another file or directory fails with a no-space error. This is the expected upper bound for filesystem-schema sizing and benchmarks. |
 | `resources.maxWasmFuel` | WASM execution budget | Bounds WASM execution work; unset means no explicit fuel budget. |
@@ -53,6 +58,19 @@ Set caps on the `limits` object in the `agentOS` config. Limits are grouped by s
 | `process.maxSpawnFileActions` | File actions decoded for one `posix_spawn` call | Default is `4096`; excess actions fail with `E2BIG`. |
 | `process.maxSpawnFileActionBytes` | Serialized file-action bytes for one `posix_spawn` call | Default is `1 MiB`; excess input fails with `E2BIG`. |
 
+### Streaming fetch responses
+
+A VM may have at most `256` host-to-VM streaming HTTP responses open at once.
+This is a fixed runtime limit and does not have a `limits` configuration field.
+A stream occupies one slot after `fetchStreamStart()` returns and releases it
+when `fetchStreamRead()` reports `done: true` or the host calls
+`fetchStreamCancel()`. Opening another stream at the limit fails with
+`ERR_AGENTOS_VM_FETCH_STREAM_LIMIT`.
+
+This limit bounds concurrent streams, not the number of requests a warm VM can
+serve over its lifetime. Completed and cancelled streams do not accumulate
+toward the limit.
+
 ## Behavior at the limit
 
 - **WASM stack**: deep recursion throws a stack-overflow error in the guest, never a host crash.

vendor/agentos/docs/content/docs/system-prompt.mdx

@@ -14,5 +14,6 @@ The base prompt is embedded in the sidecar (not written to a file inside the VM)
 
 - `additionalInstructions` appends session-specific text after the base OS prompt and before the generated binding docs, rather than replacing the agent's own instructions.
 - `skipOsInstructions` suppresses the base OS prompt while still injecting the generated binding docs.
+- For Claude Code, `ACP_SYSTEM_PROMPT_MODE=replace` in the session `env` replaces Claude Code's built-in system prompt with the assembled prompt. See [Claude Code](/agentos/docs/agents/claude#system-prompt).
 
 <CodeSnippet file="examples/sessions/client.ts" region="system-prompt" />

vendor/agentos/examples/bindings/README.md

@@ -9,7 +9,7 @@ Give an agent access to your own host code—API calls, database lookups, intern
 
 ## How it works
 
-A binding collection bundles a `name`, a `description`, and a map of named `bindings`. Each binding declares a Zod `inputSchema`, an `execute` handler that runs on the host, and optional `examples`. Pass collections to `agentOS({ bindings: [...] })`; AgentOS exposes each collection as `/usr/local/bin/agentos-{name}` inside the VM. When an agent invokes a binding, its schema validates the arguments before the handler executes host-side.
+A binding collection bundles a `name`, a `description`, and a map of named `bindings`. Each binding declares a Zod `inputSchema`, an `execute` handler that runs on the host, and optional `examples`. Pass collections to `agentOS({ bindings: [...] })`; AgentOS exposes each collection as `/bin/agentos-{name}` inside the VM. When an agent invokes a binding, its schema validates the arguments before the handler executes host-side.
 
 ## Run it
 

vendor/agentos/examples/bindings/server.ts

@@ -3,7 +3,7 @@ import { z } from "zod";
 
 // Define a group of bindings (host functions). Each binding has a Zod input
 // schema and an `execute` handler that runs on the host. The group is exposed to
-// the agent as a CLI command at /usr/local/bin/agentos-{name} inside the VM.
+// the agent as a CLI command at /bin/agentos-{name} inside the VM.
 const weatherBindings = {
 	name: "weather",
 	description: "Weather data bindings",

vendor/agentos/examples/browserbase/client-direct.ts

@@ -17,7 +17,11 @@ const env = {
 
 const { stdout } = await agent.process.exec("browse cloud fetch https://example.com", {
 	env,
+	output: { capture: "all" },
 });
+if (!stdout) {
+	throw new Error("Browserbase command returned no output");
+}
 
 const page = JSON.parse(stdout) as { statusCode: number; content: string };
 console.log(`fetched status ${page.statusCode}`);

vendor/agentos/examples/browserbase/client.ts

@@ -18,7 +18,11 @@ const env = {
 
 const { stdout } = await agent.process.exec("browse cloud fetch https://example.com", {
 	env,
+	output: { capture: "all" },
 });
+if (!stdout) {
+	throw new Error("Browserbase command returned no output");
+}
 
 const page = JSON.parse(stdout) as { statusCode: number; content: string };
 console.log(`fetched status ${page.statusCode}`);

vendor/agentos/examples/claude/client.ts

@@ -6,7 +6,7 @@ const client = createClient<typeof registry>({
 });
 const agent = client.vm.getOrCreate("my-agent");
 
-// ── Quick start ───────────────────────────────────────────────────
+// ── Quickstart ────────────────────────────────────────────────────
 async function quickStart() {
 	// docs:start quickstart
 	await agent.sessions.open({

vendor/agentos/examples/codex/client.ts

@@ -7,7 +7,7 @@ const client = createClient<typeof registry>({
 });
 const agent = client.vm.getOrCreate("my-agent");
 
-// ── Quick start ───────────────────────────────────────────────────
+// ── Quickstart ────────────────────────────────────────────────────
 async function quickStart() {
 	await agent.sessions.open({
 		agent: "codex",

vendor/agentos/examples/embedded/limits.ts

@@ -1,8 +1,13 @@
 import { AgentOs } from "@rivet-dev/agentos-core";
 
+const sidecar = await AgentOs.createSidecar({
+	runtime: { executor: { maxActiveVms: 8 } },
+});
+
 // The same `limits` object the actor takes. `onLimitWarning` is an embedded
 // create option rather than a broadcast event, so it fires only in this process.
 const vm = await AgentOs.create({
+	sidecar: { kind: "explicit", handle: sidecar },
 	limits: {
 		resources: { maxProcesses: 64, maxFilesystemBytes: 256 * 1024 * 1024 },
 		jsRuntime: { v8HeapLimitMb: 128, cpuTimeLimitMs: 30_000 },
@@ -12,3 +17,4 @@ const vm = await AgentOs.create({
 	},
 });
 await vm.dispose();
+await sidecar.dispose();

vendor/agentos/examples/filesystem/isolation.ts

@@ -18,8 +18,8 @@ const result = await agent.process.exec(`node -e '
   const note = readFileSync("/home/agentos/note.txt", "utf8").trim();
   console.log("guest read seed:", JSON.stringify(seed));
   console.log("guest read note:", note);
-'`);
-console.log("guest stdout:", result.stdout.trim());
+'`, { output: { capture: "all" } });
+console.log("guest stdout:", (result.stdout ?? "").trim());
 
 // Read a guest-written file back on the host.
 const bytes = await agent.filesystem.readFile("/home/agentos/seed.json");

vendor/agentos/examples/js-sdk-overview/src/contexts.ts

@@ -5,13 +5,16 @@ const runtime = await AgentOs.create();
 try {
 	await runtime.createContext("analysis");
 
-	await runtime.javascript.execute("const answer = 40", {
+	await runtime.javascript.execute("globalThis.answer = 40", {
 		contextId: "analysis",
 	});
 
-	const result = await runtime.javascript.evaluate<number>("answer + 2", {
-		contextId: "analysis",
-	});
+	const result = await runtime.javascript.evaluate<number>(
+		"globalThis.answer + 2",
+		{
+			contextId: "analysis",
+		},
+	);
 	console.log(result.outcome === "succeeded" ? result.value : result.error); // 42
 
 	// Delete an idle context when you are done with it. `contexts.reset()`

vendor/agentos/examples/opencode/client.ts

@@ -6,7 +6,7 @@ const client = createClient<typeof registry>({
 });
 const agent = client.vm.getOrCreate("my-agent");
 
-// ── Quick start ───────────────────────────────────────────────────
+// ── Quickstart ────────────────────────────────────────────────────
 async function quickStart() {
 	// docs:start quickstart
 	await agent.sessions.open({

vendor/agentos/examples/pi/README.md

@@ -1,11 +1,11 @@
 ---
 title: "Pi Agent"
-description: "Run the Pi coding agent in a session, including quick start and session management."
+description: "Run the Pi coding agent in a session, including quickstart and session management."
 category: "Agents"
 order: 1
 ---
 
-Spin up the Pi coding agent inside a VM, open a session, and send it prompts. Reach for this when you want an end-to-end agent loop — quick start plus the session knobs for skills and MCP servers.
+Spin up the Pi coding agent inside a VM, open a session, and send it prompts. Reach for this when you want an end-to-end agent loop from quickstart through the session knobs for skills and MCP servers.
 
 ## How it works
 

vendor/agentos/examples/pi/client.ts

@@ -6,8 +6,8 @@ const client = createClient<typeof registry>({
 });
 const agent = client.vm.getOrCreate("my-agent");
 
-// ── Quick start ───────────────────────────────────────────────────
-// docs:start quick-start
+// ── Quickstart ────────────────────────────────────────────────────
+// docs:start quickstart
 async function quickStart() {
 	await agent.sessions.open({
 		agent: "pi",
@@ -21,7 +21,7 @@ async function quickStart() {
 	});
 	console.log(result.message?.content ?? []);
 }
-// docs:end quick-start
+// docs:end quickstart
 
 // ── Skills ────────────────────────────────────────────────────────
 //

vendor/agentos/examples/processes/lifecycle.ts

@@ -8,20 +8,15 @@ const agent = client.vm.getOrCreate("my-agent");
 
 const { pid } = await agent.process.spawn("node", ["/home/agentos/server.js"]);
 
-const processStatus = (process: {
-	running: boolean;
-	exitCode?: number | null;
-}) => (process.running ? "running" : `exited ${process.exitCode ?? ""}`.trim());
-
 // List all processes tracked by the VM
 const processes = await agent.process.list();
 for (const p of processes) {
-	console.log(p.pid, p.command, p.args.join(" "), processStatus(p));
+	console.log(p.pid, p.command, p.state);
 }
 
 // Inspect a specific process by pid
 const info = await agent.process.get(pid);
-console.log(processStatus(info), info.exitCode);
+console.log(info.pid, info.state);
 
 // Graceful stop (SIGTERM)
 await agent.process.signal(pid, "SIGTERM");

vendor/agentos/examples/processes/visibility.ts

@@ -4,18 +4,15 @@ import type { registry } from "./server";
 const client = createClient<typeof registry>({ endpoint: "http://localhost:6420" });
 const agent = client.vm.getOrCreate("my-agent");
 
-const processStatus = (process: { running: boolean; exitCode?: number | null }) =>
-  process.running ? "running" : `exited ${process.exitCode ?? ""}`.trim();
-
 // All processes spawned in the VM
 const all = await agent.process.list();
 for (const p of all) {
-  console.log(p.pid, p.command, p.args.join(" "), processStatus(p));
+  console.log(p.pid, p.command, p.state);
 }
 
 // Inspect a single process by pid
 const first = all[0];
 if (first) {
   const info = await agent.process.get(first.pid);
-  console.log(info.pid, info.command, "status:", processStatus(info));
+  console.log(info.pid, info.command, "status:", info.state);
 }

vendor/agentos/examples/quickstart/bindings/index.ts

@@ -47,11 +47,15 @@ const vm = await AgentOs.create({
 });
 
 try {
-	const weather = await vm.process.exec("agentos-weather get --city London");
-	console.log("Weather:", weather.stdout.trim());
+	const weather = await vm.process.exec("agentos-weather get --city London", {
+		output: { capture: "all" },
+	});
+	console.log("Weather:", (weather.stdout ?? "").trim());
 
-	const sum = await vm.process.exec("agentos-calc add --a 10 --b 32");
-	console.log("Sum:", sum.stdout.trim());
+	const sum = await vm.process.exec("agentos-calc add --a 10 --b 32", {
+		output: { capture: "all" },
+	});
+	console.log("Sum:", (sum.stdout ?? "").trim());
 } finally {
 	await vm.dispose();
 }