ai-agent-workspace

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AI Agent Workspaces

AI Agent 工作区

IMPORTANT: Before doing anything, you MUST read
BASE_SKILL.md
in this skill's directory. It contains essential guidance on debugging, error handling, state management, deployment, and project setup. Those rules and patterns apply to all RivetKit work. Everything below assumes you have already read and understood it.

重要提示：在进行任何操作之前，你必须阅读本技能目录下的
BASE_SKILL.md
文件。其中包含调试、错误处理、状态管理、部署和项目设置的关键指南。这些规则和模式适用于所有RivetKit工作。以下所有内容均假设你已阅读并理解该文件。

Working Examples

实用示例

If you need a reference implementation, read the raw working example code in these templates:

agent-os

Patterns for giving every AI agent its own computer with agentOS: one Rivet Actor per agent that owns a portable, lightweight in-process OS running on Wasm and V8. Use it for code interpreters that keep state between runs, agents that ship artifacts behind shareable preview URLs, per-user dev environments, and scheduled maintenance agents. agentOS is in preview and the API is subject to change.

This entry is about giving an agent a workspace. For conversation memory, message queues, and streaming chat patterns, see AI Agent.

如果你需要参考实现，可以查看以下模板中的完整实用示例代码：

agent-os

借助agentOS为每个AI Agent打造专属计算环境的模式：每个Agent对应一个Rivet Actor，该Actor拥有一个基于Wasm和V8运行的可移植轻量进程内操作系统。可用于在多次运行间保持状态的代码解释器、可通过共享预览URL交付产物的Agent、面向用户的开发环境以及定时维护Agent。agentOS目前处于预览阶段，API可能会发生变更。

本文档聚焦于为Agent提供工作区。如需了解对话记忆、消息队列和流式聊天模式，请查看AI Agent。

Starter Code

入门代码

The agent-os collection is reference code, one sub-example per capability; treat it as patterns to copy into your project rather than a turnkey app. The agent-os-e2e example is the complete end-to-end walkthrough.

Example	Starter Code	Use When
Hello World	GitHub	You want the minimal loop: boot a VM lazily on the first action, write a file, read it back.
Filesystem	GitHub	The agent needs the full file surface: recursive listing, stat, move, delete, and custom mounts.
Git	GitHub	The agent works with real git repos inside the workspace: init, commit, branch, and clone via `exec` .
Processes	GitHub	The agent runs shell commands with pipes and long-lived spawned programs.
Network	GitHub	The agent serves HTTP inside the VM and you need `vmFetch` or signed preview URLs.
Cron	GitHub	The workspace runs scheduled commands or recurring agent work.
Tools	GitHub	You want your backend functions exposed as CLI commands inside the workspace.
Agent Session	GitHub	You drive a Pi coding agent session inside the workspace. Requires `ANTHROPIC_API_KEY` .
Sandbox Mounting	GitHub	The agent needs native binaries or a real OS, mounted into the VM from a Docker-backed sandbox. Requires Docker.
End-to-End Walkthrough	GitHub	You want one runnable script covering files, processes, preview URLs, and a streaming Pi agent session.

agent-os集合是参考代码，每个子示例对应一项功能；请将其视为可复制到你的项目中的模式，而非开箱即用的应用。agent-os-e2e示例则是完整的端到端演练。

示例	入门代码	使用场景
Hello World	GitHub	你需要最小化循环：在首次操作时延迟启动VM，写入文件并读取返回内容。
文件系统	GitHub	Agent需要完整的文件操作能力：递归列出文件、获取文件状态、移动、删除以及自定义挂载。
Git	GitHub	Agent在工作区内操作真实Git仓库：通过 `exec` 执行初始化、提交、分支和克隆操作。
进程	GitHub	Agent运行带管道的Shell命令和长期运行的衍生程序。
网络	GitHub	Agent在VM内部提供HTTP服务，你需要使用 `vmFetch` 或签名预览URL。
Cron	GitHub	工作区运行定时命令或周期性Agent任务。
工具	GitHub	你希望将后端函数作为CLI命令暴露在工作区内。
Agent会话	GitHub	你在工作区内驱动Pi编码Agent会话。需要 `ANTHROPIC_API_KEY` 。
沙箱挂载	GitHub	Agent需要原生二进制文件或真实操作系统，通过基于Docker的沙箱挂载到VM中。需要Docker。
端到端演练	GitHub	你需要一个可运行的脚本，涵盖文件操作、进程、预览URL以及流式Pi Agent会话。

Setup

设置

The whole backend is one registry with one

agentOs()

actor:

typescript

import { agentOs } from "rivetkit/agent-os";
import { setup } from "rivetkit";
import common from "@rivet-dev/agent-os-common";
import pi from "@rivet-dev/agent-os-pi";

const vm = agentOs({
  options: { software: [common, pi] },
});

export const registry = setup({ use: { vm } });
registry.start();

See the Quickstart for the client side and project layout.

整个后端是一个包含

agentOs()

actor的注册表：

typescript

import { agentOs } from "rivetkit/agent-os";
import { setup } from "rivetkit";
import common from "@rivet-dev/agent-os-common";
import pi from "@rivet-dev/agent-os-pi";

const vm = agentOs({
  options: { software: [common, pi] },
});

export const registry = setup({ use: { vm } });
registry.start();

客户端侧和项目布局请查看快速开始。

Workspace Model

工作区模型

One actor per workspace, key as identity.
```
client.vm.getOrCreate(["my-agent"])
```
gives each agent its own workspace; key by user id for per-user dev environments. Each workspace has its own filesystem, processes, and networking with no shared state and no cross-contamination (see the overview).
Software packages choose what is installed. agentOS starts with no commands installed. The
```
software
```
option installs packages such as
```
@rivet-dev/agent-os-common
```
(a meta-package of Wasm command-line tools: coreutils, sed, grep, gawk, findutils, diffutils, tar, and gzip),
```
@rivet-dev/agent-os-git
```
(git), and
```
@rivet-dev/agent-os-pi
```
(the Pi coding agent). See Software.
The VM boots lazily and sleeps when idle. The first action boots the VM (clients see a
```
vmBooted
```
event); when nothing is active, the actor sleeps and broadcasts
```
vmShutdown
```
, then wakes on the next action.

What survives a sleep/wake cycle (see Persistence):

Data	Across sleep/wake
Session transcripts and event history	Persist in actor SQLite as events stream. `listPersistedSessions` and `getSessionEvents` read them back without booting the VM, and `resumeSession` picks a session back up in a rebooted VM.
Signed preview URL tokens	Persist in actor SQLite. Requests are validated against the stored token and the VM reboots lazily to serve them, so preview URLs keep working after sleep.
Files	Persist when the mount is backed by a persistent driver (database-backed, S3, or a sandbox mount). In-memory mounts come back empty on wake.
Processes, shells, and cron jobs	Do not persist. Restart long-running processes and reschedule cron jobs on wake (recommended extension).

The actor holds itself awake while sessions, processes, shells, or hooks are active, then sleeps after a grace period.

每个工作区对应一个actor，以密钥作为标识。
```
client.vm.getOrCreate(["my-agent"])
```
为每个Agent提供专属工作区；对于面向用户的开发环境，可按用户ID作为密钥。每个工作区拥有独立的文件系统、进程和网络，无共享状态且不会相互污染（详见概述）。
软件包决定安装内容。 agentOS初始状态下未安装任何命令。
```
software
```
选项用于安装如
```
@rivet-dev/agent-os-common
```
（包含Wasm命令行工具的元包：coreutils、sed、grep、gawk、findutils、diffutils、tar和gzip）、
```
@rivet-dev/agent-os-git
```
（Git）以及
```
@rivet-dev/agent-os-pi
```
（Pi编码Agent）等软件包。详见软件。
VM延迟启动，空闲时休眠。 首次操作会启动VM（客户端会收到
```
vmBooted
```
事件）；当无活动任务时，actor进入休眠状态并广播
```
vmShutdown
```
事件，下次操作时唤醒。

休眠/唤醒周期中保留的数据（详见持久化）：

数据	休眠/唤醒后是否保留
会话记录和事件历史	以事件流形式持久化在actor的SQLite中。无需启动VM即可通过 `listPersistedSessions` 和 `getSessionEvents` 读取， `resumeSession` 可在重启后的VM中恢复会话。
签名预览URL令牌	持久化在actor的SQLite中。请求会根据存储的令牌进行验证，VM会延迟启动以处理请求，因此预览URL在休眠后仍可正常工作。
文件	当挂载使用持久化驱动（基于数据库、S3或沙箱挂载）时会保留。内存挂载在唤醒后会清空。
进程、Shell和Cron任务	不保留。建议在唤醒后重启长期运行的进程并重新调度Cron任务。

当会话、进程、Shell或钩子处于活动状态时，actor会保持唤醒，在一段宽限期后进入休眠。

Capability Tour

功能概览

Area	Use It For	Key Actions	Docs	Example
Filesystem	Give the agent a file tree to read and write	`readFile` , `writeFile` , `mkdir` , `readdir` , `move`	Filesystem	GitHub
Processes	Run commands and long-lived programs	`exec` , `spawn` , `waitProcess` , `killProcess`	Processes	GitHub
Shells	Interactive terminals with streamed output	`openShell` , `writeShell` , `resizeShell` , `closeShell`	Processes	No standalone example
Networking and preview URLs	Reach services inside the VM and share them externally	`vmFetch` , `createSignedPreviewUrl` , `expireSignedPreviewUrl`	Networking	GitHub
Cron	Scheduled commands and recurring agent sessions	`scheduleCron` , `listCronJobs` , `cancelCronJob`	Cron	GitHub
Agent sessions	Drive a coding agent inside the workspace	`createSession` , `sendPrompt` , `resumeSession` , `closeSession`	Sessions	GitHub

Two details worth knowing up front:

```
createSignedPreviewUrl
```
returns a relative path plus the token and expiry. Build the full URL with the client handle's
```
getGatewayUrl()
```
method; it is a client method, not an actor action.
Schedule cron jobs through the actor with the
```
exec
```
and
```
session
```
action types only. Callback cron actions are defined in server code and do not serialize through
```
listCronJobs
```
.

领域	适用场景	核心操作	文档	示例
文件系统	为Agent提供可读写的文件树	`readFile` , `writeFile` , `mkdir` , `readdir` , `move`	文件系统	GitHub
进程	运行命令和长期运行的程序	`exec` , `spawn` , `waitProcess` , `killProcess`	进程	GitHub
Shell	带流式输出的交互式终端	`openShell` , `writeShell` , `resizeShell` , `closeShell`	进程	无独立示例
网络和预览URL	访问VM内部服务并对外共享	`vmFetch` , `createSignedPreviewUrl` , `expireSignedPreviewUrl`	网络	GitHub
Cron	定时命令和周期性Agent会话	`scheduleCron` , `listCronJobs` , `cancelCronJob`	Cron	GitHub
Agent会话	在工作区内驱动编码Agent	`createSession` , `sendPrompt` , `resumeSession` , `closeSession`	会话	GitHub

需要提前了解的两个细节：

```
createSignedPreviewUrl
```
返回相对路径、令牌和过期时间。需使用客户端句柄的
```
getGatewayUrl()
```
方法构建完整URL；这是客户端方法，而非actor操作。
仅通过actor的
```
exec
```
和
```
session
```
操作类型调度Cron任务。回调式Cron任务在服务器代码中定义，不会通过
```
listCronJobs
```
序列化。

Driving a Coding Agent Session

驱动编码Agent会话

Only the Pi agent (

@rivet-dev/agent-os-pi

) is currently supported as a session agent; Amp, Claude Code, Codex, and OpenCode are coming soon. See Sessions.

```
createSession("pi", { env: { ANTHROPIC_API_KEY } })
```
returns a
```
sessionId
```
. The VM does not inherit the host
```
process.env
```
, so API keys are passed explicitly per session or kept server-side through the LLM gateway.
Open a realtime connection and subscribe to
```
sessionEvent
```
to stream the agent's output, such as message chunks, as it works.
```
sendPrompt(sessionId, ...)
```
starts a turn;
```
cancelPrompt
```
stops one in flight.
When the agent asks to use a tool, clients receive a
```
permissionRequest
```
event and answer with
```
respondPermission
```
, or the server auto-approves with the
```
onPermissionRequest
```
config hook (see Permissions).
Transcripts are persisted automatically in the universal transcript format (Agent Communication Protocol, ACP). After sleep,
```
resumeSession
```
continues a session in the rebooted VM, and
```
listPersistedSessions
```
plus
```
getSessionEvents
```
read history without booting the VM at all.

目前仅支持Pi Agent (

@rivet-dev/agent-os-pi

)作为会话Agent；Amp、Claude Code、Codex和OpenCode即将支持。详见会话。

```
createSession("pi", { env: { ANTHROPIC_API_KEY } })
```
返回
```
sessionId
```
。VM不会继承宿主
```
process.env
```
，因此需为每个会话显式传入API密钥，或通过LLM网关在服务器端保存密钥。
建立实时连接并订阅
```
sessionEvent
```
，以流式获取Agent的输出（如消息片段）。
```
sendPrompt(sessionId, ...)
```
启动一轮对话；
```
cancelPrompt
```
可终止正在进行的对话。
当Agent请求使用工具时，客户端会收到
```
permissionRequest
```
事件，并通过
```
respondPermission
```
进行人工审批，或通过服务器端
```
onPermissionRequest
```
配置钩子自动审批（详见权限）。
会话记录会自动以通用记录格式（Agent Communication Protocol, ACP）持久化。休眠后，
```
resumeSession
```
可在重启后的VM中恢复会话，无需启动VM即可通过
```
listPersistedSessions
```
和
```
getSessionEvents
```
读取历史记录。

Host Tools

宿主工具

Expose your backend functions to the agent as CLI commands inside the workspace. Define a toolkit with

toolKit()

and

hostTool()

(Zod-schema'd JavaScript functions on the host), pass it via

agentOs({ options: { toolKits: [...] } })

, and it is installed as a command such as

agentos-weather forecast --city Paris --days 3

and injected into the agent's system prompt. The agent calls your backend with no HTTP endpoints or MCP servers to stand up, and CLI-shaped tools are code mode compatible for large token savings. See Tools and the tools example.

将后端函数作为CLI命令暴露给工作区内的Agent。使用

toolKit()

和

hostTool()

（宿主上的Zod模式验证JavaScript函数）定义工具包，通过

agentOs({ options: { toolKits: [...] } })

传入，即可安装为

agentos-weather forecast --city Paris --days 3

这类命令，并注入到Agent的系统提示词中。Agent无需HTTP端点或MCP服务器即可调用你的后端，且CLI形式的工具与代码模式兼容，可大幅节省令牌消耗。详见工具和工具示例。

When to Mount a Full Sandbox

何时挂载完整沙箱

agentOS is not a replacement for sandboxes; it is designed to work alongside them. When a workspace needs native binaries, browsers, compilation, or desktop automation, use sandbox mounting: start a Docker-backed sandbox with

SandboxAgent.start({ sandbox: docker() })

, project its filesystem into the VM as a native directory (for example

/sandbox

) with

createSandboxFs

, and expose sandbox process control as host tools with

createSandboxToolkit

. Filesystem actions like

writeFile

and

readFile

project transparently through the mount while heavy workloads run in the container.

See Sandbox Mounting for the hybrid model and agentOS vs Sandboxes for when each side wins: the lightweight VM has a near-zero cold start (~6 ms) and installs with

npm install

, while sandboxes are full Linux environments billed per second of uptime.

agentOS并非沙箱的替代品，而是设计为与沙箱协同工作。当工作区需要原生二进制文件、浏览器、编译或桌面自动化时，可使用沙箱挂载：通过

SandboxAgent.start({ sandbox: docker() })

启动基于Docker的沙箱，使用

createSandboxFs

将其文件系统映射为VM中的原生目录（例如

/sandbox

），并使用

createSandboxToolkit

将沙箱进程控制作为宿主工具暴露。

writeFile

和

readFile

等文件系统操作会透明地通过挂载映射，而繁重的工作负载则在容器中运行。

混合模式详见沙箱挂载，何时使用哪种方案详见agentOS vs 沙箱：轻量VM冷启动时间极短（约6毫秒），可通过

npm install

安装；而沙箱是完整的Linux环境，按运行时长计费。

Architecture

架构

Topic	Summary
Topology	One `vm[workspaceId]` actor per agent or per user; the actor key is the workspace identity.
Ingress	Actor actions for files, processes, networking, cron, and sessions; a realtime connection for streamed events.
Streaming	`sessionEvent` per agent event, `processOutput` and `processExit` for spawned processes, `shellData` for interactive shells.
Persistence	Session transcripts, event history, and preview tokens in actor SQLite; files persist through persistent mounts.

Actors

Key:

vm[workspaceId]

, for example

client.vm.getOrCreate(["my-agent"])

Responsibility: Owns one workspace. Boots the VM lazily on the first action, serves all capability actions, proxies signed preview URL requests into the VM's virtual network, and persists sessions and tokens to actor SQLite.

Actions (grouped; the most load-bearing of each area)

Filesystem:

readFile

writeFile

mkdir

readdir

readdirRecursive

stat

exists

move

deleteFile

Processes:

exec

spawn

writeProcessStdin

waitProcess

listProcesses

killProcess

Shells:

openShell

writeShell

resizeShell

closeShell

Network:

vmFetch

createSignedPreviewUrl

expireSignedPreviewUrl

Cron:
```
scheduleCron
```
,
```
listCronJobs
```
,
```
cancelCronJob
```

Sessions:

createSession

sendPrompt

cancelPrompt

respondPermission

resumeSession

closeSession

destroySession

listPersistedSessions

getSessionEvents

Queues
- None

Events

```
vmBooted
```
```
vmShutdown
```
```
sessionEvent
```
```
permissionRequest
```
```
processOutput
```
```
processExit
```
```
shellData
```
```
cronEvent
```

State
- SQLite
- ```
agent_os_sessions
```
  and
```
agent_os_session_events
```
  (session metadata plus seq-ordered transcript events)
- ```
agent_os_preview_tokens
```
  (signed preview URL tokens with expiry)
- ```
agent_os_fs_entries
```
  (file content for database-backed mounts)

Lifecycle

mermaid

sequenceDiagram
	participant C as Client
	participant A as vm actor
	participant V as agentOS VM
	participant P as Pi session

	C->>A: getOrCreate(["my-agent"])
	C->>A: writeFile("/tmp/hello.txt", ...)
	Note over A,V: first action boots the VM
	A-->>C: vmBooted
	C->>A: exec("echo hello | tr a-z A-Z")
	A->>V: run command
	V-->>A: {exitCode: 0, stdout}
	C->>A: spawn("node", ["/tmp/server.mjs"])
	C->>A: createSignedPreviewUrl(8080, 60)
	A-->>C: {path, token, expiresAt}
	C->>A: fetch(gatewayUrl + path)
	Note over A: token checked in SQLite, request proxied into the VM network
	C->>A: createSession("pi", {env})
	A->>P: start session
	C->>A: sendPrompt(sessionId, ...)
	loop streamed agent output
		P-->>A: agent event
		A-->>C: sessionEvent
	end
	Note over A: idle, sleeps after grace period (vmShutdown)
	C->>A: resumeSession(sessionId)
	Note over A,V: wake reboots the VM, restoring transcripts, preview tokens, and persistent mounts

主题	概述
拓扑	每个Agent或用户对应一个 `vm[workspaceId]` actor；actor密钥即为工作区标识。
入口	用于文件、进程、网络、Cron和会话的actor操作；用于流式事件的实时连接。
流式传输	`sessionEvent` 对应Agent事件， `processOutput` 和 `processExit` 对应衍生进程， `shellData` 对应交互式Shell。
持久化	会话记录、事件历史和预览令牌存储在actor的SQLite中；文件通过持久化挂载保留。

Actors

密钥:

vm[workspaceId]

，例如

client.vm.getOrCreate(["my-agent"])

职责: 管理一个工作区。在首次操作时延迟启动VM，处理所有功能操作，将签名预览URL请求代理到VM的虚拟网络，并将会话和令牌持久化到actor的SQLite中。

操作（分组；各领域最核心的操作）

文件系统:

readFile

writeFile

mkdir

readdir

readdirRecursive

stat

exists

move

deleteFile

进程:

exec

spawn

writeProcessStdin

waitProcess

listProcesses

killProcess

Shell:

openShell

writeShell

resizeShell

closeShell

网络:

vmFetch

createSignedPreviewUrl

expireSignedPreviewUrl

Cron:
```
scheduleCron
```
,
```
listCronJobs
```
,
```
cancelCronJob
```

会话:

createSession

sendPrompt

cancelPrompt

respondPermission

resumeSession

closeSession

destroySession

listPersistedSessions

getSessionEvents

队列
- 无

事件

```
vmBooted
```
```
vmShutdown
```
```
sessionEvent
```
```
permissionRequest
```
```
processOutput
```
```
processExit
```
```
shellData
```
```
cronEvent
```

状态
- SQLite
- ```
agent_os_sessions
```
  和
```
agent_os_session_events
```
  （会话元数据及按顺序排列的记录事件）
- ```
agent_os_preview_tokens
```
  （带过期时间的签名预览URL令牌）
- ```
agent_os_fs_entries
```
  （基于数据库挂载的文件内容）

生命周期

mermaid

sequenceDiagram
	participant C as Client
	participant A as vm actor
	participant V as agentOS VM
	participant P as Pi session

	C->>A: getOrCreate(["my-agent"])
	C->>A: writeFile("/tmp/hello.txt", ...)
	Note over A,V: first action boots the VM
	A-->>C: vmBooted
	C->>A: exec("echo hello | tr a-z A-Z")
	A->>V: run command
	V-->>A: {exitCode: 0, stdout}
	C->>A: spawn("node", ["/tmp/server.mjs"])
	C->>A: createSignedPreviewUrl(8080, 60)
	A-->>C: {path, token, expiresAt}
	C->>A: fetch(gatewayUrl + path)
	Note over A: token checked in SQLite, request proxied into the VM network
	C->>A: createSession("pi", {env})
	A->>P: start session
	C->>A: sendPrompt(sessionId, ...)
	loop streamed agent output
		P-->>A: agent event
		A-->>C: sessionEvent
	end
	Note over A: idle, sleeps after grace period (vmShutdown)
	C->>A: resumeSession(sessionId)
	Note over A,V: wake reboots the VM, restoring transcripts, preview tokens, and persistent mounts

Security Checklist

安全检查清单

Authenticate connections: Add the
```
onBeforeConnect
```
hook in the
```
agentOs()
```
config so only authorized callers reach a workspace. Signed preview URL requests deliberately skip it because the token is the credential; browsers navigating a preview URL cannot supply actor connection params.
Gate agent tool use with permissions: Session permission requests broadcast as
```
permissionRequest
```
events for human-in-the-loop approval via
```
respondPermission
```
, or run a server-side
```
onPermissionRequest
```
policy for automated pipelines. See Permissions.
Treat preview URLs as bearer credentials: Tokens are randomly generated 32-character values with a default expiry of 1 hour and a maximum of 24; revoke early with
```
expireSignedPreviewUrl
```
. Preview responses carry permissive CORS headers, so do not serve private data on a preview port without app-level auth.
Keep LLM credentials off the browser: Create sessions from trusted server code with the key in
```
createSession
```
env, or keep keys entirely server-side with the LLM gateway. Session keys are injected into the session environment inside the VM and are never stored in actor config or SQLite.
Treat mounted sandboxes as their own trust boundary: A mounted sandbox is a full Linux environment outside the workspace's Wasm and V8 isolate. Scope what its network and filesystem can reach before projecting it into an agent's VM.
Set resource and cost limits: Cap per-workspace memory and CPU (
```
maxMemoryMb
```
,
```
maxCpuPercent
```
, see Security). Active sessions, processes, and shells hold the actor awake, so add per-workspace session caps and token budgets as a recommended extension.

验证连接: 在
```
agentOs()
```
配置中添加
```
onBeforeConnect
```
钩子，确保只有授权调用者可访问工作区。签名预览URL请求会刻意跳过该验证，因为令牌是凭证；浏览器访问预览URL时无法提供actor连接参数。
通过权限控制Agent工具使用: 会话权限请求会以
```
permissionRequest
```
事件广播，可通过
```
respondPermission
```
进行人工审批，或通过服务器端
```
onPermissionRequest
```
策略实现自动化流水线审批。详见权限。
将预览URL视为Bearer凭证: 令牌是随机生成的32位值，默认过期时间为1小时，最长为24小时；可通过
```
expireSignedPreviewUrl
```
提前撤销。预览响应带有宽松的CORS头，因此若无应用级认证，请勿在预览端口提供私有数据。
避免在浏览器中存储LLM凭证: 从可信服务器代码创建会话，在
```
createSession
```
的env中传入密钥，或通过LLM网关在服务器端完全保存密钥。会话密钥会注入到VM内部的会话环境中，绝不会存储在actor配置或SQLite中。
将挂载的沙箱视为独立信任边界: 挂载的沙箱是工作区Wasm和V8隔离环境之外的完整Linux环境。在将其映射到Agent的VM之前，需限制其网络和文件系统访问范围。
设置资源和成本限制: 限制每个工作区的内存和CPU（
```
maxMemoryMb
```
,
```
maxCpuPercent
```
，详见安全）。活动会话、进程和Shell会保持actor唤醒，因此建议扩展功能以添加每个工作区的会话上限和令牌预算。

Reference Map

参考地图

Actors

Access Control
Actions
Actor Keys
Actor Scheduling
Actor Statuses
AI and User-Generated Rivet Actors
Authentication
Communicating Between Actors
Connections
Custom Inspector Tabs
Debugging
Design Patterns
Destroying Actors
Errors
Fetch and WebSocket Handler
Helper Types
Icons & Names
Input Parameters
Lifecycle
Limits
Low-Level HTTP Request Handler
Low-Level KV Storage
Low-Level WebSocket Handler
Metadata
Next.js Quickstart
Node.js & Bun Quickstart
Queues & Run Loops
React Quickstart
Realtime
Rust Quickstart (Preview)
Sandbox Actor
Scaling & Concurrency
Sharing and Joining State
SQLite
SQLite + Drizzle
State & Storage
Testing
Troubleshooting
Types
Vanilla HTTP API
Versions & Upgrades
Workflows

访问控制
操作
Actor密钥
Actor调度
Actor状态
AI和用户生成的Rivet Actors
认证
Actor间通信
连接
自定义检查器标签
调试
设计模式
销毁Actors
错误
Fetch和WebSocket处理器
辅助类型
图标与名称
输入参数
生命周期
限制
底层HTTP请求处理器
底层KV存储
底层WebSocket处理器
元数据
Next.js快速开始
Node.js & Bun快速开始
队列与运行循环
React快速开始
实时功能
Rust快速开始（预览）
沙箱Actor
扩展与并发
共享与合并状态
SQLite
SQLite + Drizzle
状态与存储
测试
故障排除
类型
原生HTTP API
版本与升级
工作流

Agent Os

Agent-to-Agent Communication
agentOS vs Sandbox
Authentication
Benchmarks
Configuration
Core Package
Cron Jobs
Deployment
Embedded LLM Gateway
Events
Filesystem
Limitations
LLM Credentials
Multiplayer
Networking & Previews
Overview
Permissions
Persistence & Sleep
Pi
Processes & Shell
Queues
Quickstart
Sandbox Mounting
Security & Auth
Security Model
Sessions
Software
SQLite
System Prompt
Tools
Webhooks
Workflow Automation

Agent间通信
agentOS vs 沙箱
认证
基准测试
配置
核心包
Cron任务
部署
嵌入式LLM网关
事件
文件系统
限制
LLM凭证
多人协作
网络与预览
概述
权限
持久化与休眠
Pi
进程与Shell
队列
快速开始
沙箱挂载
安全与认证
安全模型
会话
软件
SQLite
系统提示词
工具
Webhooks
工作流自动化

Clients

Node.js & Bun
React
Swift
SwiftUI

Node.js & Bun
React
Swift
SwiftUI

Connect

Deploy To Amazon Web Services Lambda
Deploying to AWS ECS
Deploying to Cloudflare Workers
Deploying to Freestyle
Deploying to Google Cloud Run
Deploying to Hetzner
Deploying to Kubernetes
Deploying to Railway
Deploying to Rivet Compute
Deploying to Supabase Functions
Deploying to Vercel
Deploying to VMs & Bare Metal

部署到Amazon Web Services Lambda
部署到AWS ECS
部署到Cloudflare Workers
部署到Freestyle
部署到Google Cloud Run
部署到Hetzner
部署到Kubernetes
部署到Railway
部署到Rivet Compute
部署到Supabase Functions
部署到Vercel
部署到VM与裸机

Cookbook

AI Agent
AI Agent Workspaces
Chat Room
Collaborative Text Editor
Cron Jobs and Scheduled Tasks
Database per Tenant
Deploying Rivet in a VPC or Air-Gapped Network
Live Cursors and Presence
Multiplayer Game

AI Agent
AI Agent工作区
聊天室
协作文本编辑器
Cron任务与定时任务
租户专属数据库
在VPC或隔离网络中部署Rivet
实时光标与在线状态
多人游戏

General

Actor Configuration
Architecture
Cross-Origin Resource Sharing
Documentation for LLMs & AI
Edge Networking
Endpoints
Environment Variables
HTTP Server
Logging
Pool Configuration
Production Checklist
Registry Configuration
Runtime Modes

Actor配置
架构
跨域资源共享
面向LLM与AI的文档
边缘网络
端点
环境变量
HTTP服务器
日志
池配置
生产环境检查清单
注册表配置
运行时模式

Self Hosting

Configuration
Docker Compose
Docker Container
File System
FoundationDB (Enterprise)
Installing Rivet Engine
Kubernetes
Multi-Region
PostgreSQL
Production Checklist
Railway Deployment
Render Deployment
TLS & Certificates

配置
Docker Compose
Docker容器
文件系统
FoundationDB（企业版）
安装Rivet引擎
Kubernetes
多区域
PostgreSQL
生产环境检查清单
Railway部署
Render部署
TLS与证书