vercel-labs / open-agents

Open Agents is an open-source reference app for building and running background coding agents on Vercel. It includes the web UI, the agent runtime, sandbox orchestration, and the GitHub integration needed to go from prompt to code changes without keeping your laptop involved. The repo is meant to be forked and adapted, not treated as a black box. Open Agents 是一个开源参考应用，用于在 Vercel 上构建和运行后台编码智能体。它包含了 Web UI、智能体运行时、沙盒编排以及 GitHub 集成，让你无需保持电脑在线即可从提示词（Prompt）直接生成代码变更。该仓库旨在供开发者分叉（Fork）并进行适配，而不是作为一个黑盒使用。

What it is

它是什么

Open Agents is a three-layer system: Web -> Agent workflow -> Sandbox VM. The web app handles auth, sessions, chat, and streaming UI. The agent runs as a durable workflow on Vercel. The sandbox is the execution environment: filesystem, shell, git, dev servers, and preview ports. Open Agents 是一个三层系统：Web -> 智能体工作流 -> 沙盒虚拟机。Web 应用负责处理身份验证、会话、聊天和流式 UI。智能体作为持久化工作流在 Vercel 上运行。沙盒则是执行环境，包含文件系统、Shell、Git、开发服务器和预览端口。

The key architectural decision: the agent is not the sandbox. The agent does not run inside the VM. It runs outside the sandbox and interacts with it through tools like file reads, edits, search, and shell commands. That separation is the main point of the project: 核心架构决策：智能体不是沙盒。智能体不在虚拟机内部运行，而是在沙盒外部运行，并通过文件读取、编辑、搜索和 Shell 命令等工具与沙盒交互。这种分离是该项目的核心所在：

• agent execution is not tied to a single request lifecycle
• sandbox lifecycle can hibernate and resume independently
• model/provider choices and sandbox implementation can evolve separately
• the VM stays a plain execution environment instead of becoming the control plane
• 智能体执行不绑定于单一请求生命周期
• 沙盒生命周期可以独立休眠和恢复
• 模型/提供商的选择与沙盒实现可以独立演进
• 虚拟机保持为一个纯粹的执行环境，而不是成为控制平面

Current capabilities

当前功能

• chat-driven coding agent with file, search, shell, task, skill, and web tools
• durable multi-step execution with Workflow SDK-backed runs, streaming, and cancellation
• isolated Vercel sandboxes with snapshot-based resume
• repo cloning and branch work inside the sandbox
• optional auto-commit, push, and PR creation after a successful run
• session sharing via read-only links
• optional voice input via ElevenLabs transcription
• 基于聊天的编码智能体，具备文件、搜索、Shell、任务、技能和 Web 工具
• 基于 Workflow SDK 的持久化多步执行，支持运行、流式传输和取消
• 带有基于快照恢复功能的隔离 Vercel 沙盒
• 在沙盒内进行仓库克隆和分支工作
• 运行成功后可选自动提交、推送和创建 PR
• 通过只读链接分享会话
• 通过 ElevenLabs 转录实现可选的语音输入

Runtime notes

运行时说明

A few details that matter for understanding the current implementation: 以下细节对于理解当前实现至关重要：

• Chat requests start a workflow run instead of executing the agent inline.
• Each agent turn can continue across many persisted workflow steps.
• Active runs can be resumed by reconnecting to the stream for the existing workflow.
• Sandboxes use a base snapshot, expose ports 3000, 5173, 4321, and 8000, and hibernate after inactivity.
• Auto-commit and auto-PR are supported, but they are preference-driven features, not always-on behavior.
• 聊天请求会启动一个工作流运行，而不是直接内联执行智能体。
• 每个智能体轮次可以跨越多个持久化的工作流步骤持续进行。
• 活跃的运行可以通过重新连接到现有工作流的流来恢复。
• 沙盒使用基础快照，暴露 3000、5173、4321 和 8000 端口，并在不活动后休眠。
• 支持自动提交和自动 PR，但这些是基于偏好的功能，并非默认开启。

Environment variables

环境变量

See apps/web/.env.example for the full list. 完整列表请参阅 apps/web/.env.example。

Summary: 摘要：

• Minimum runtime: POSTGRES_URL=, BETTER_AUTH_SECRET=
• Required for sign-in (Vercel OAuth): NEXT_PUBLIC_VERCEL_APP_CLIENT_ID=, VERCEL_APP_CLIENT_SECRET=
• Required for GitHub repo access, pushes, and PRs: NEXT_PUBLIC_GITHUB_CLIENT_ID=, GITHUB_CLIENT_SECRET=, GITHUB_APP_ID=, GITHUB_APP_PRIVATE_KEY=, NEXT_PUBLIC_GITHUB_APP_SLUG=, GITHUB_WEBHOOK_SECRET=
• Optional: REDIS_URL=, KV_URL=, VERCEL_PROJECT_PRODUCTION_URL=, NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL=, VERCEL_SANDBOX_BASE_SNAPSHOT_ID=, ELEVENLABS_API_KEY=
• 最小运行时： POSTGRES_URL=, BETTER_AUTH_SECRET=
• 登录必需（Vercel OAuth）： NEXT_PUBLIC_VERCEL_APP_CLIENT_ID=, VERCEL_APP_CLIENT_SECRET=
• GitHub 仓库访问、推送和 PR 必需： NEXT_PUBLIC_GITHUB_CLIENT_ID=, GITHUB_CLIENT_SECRET=, GITHUB_APP_ID=, GITHUB_APP_PRIVATE_KEY=, NEXT_PUBLIC_GITHUB_APP_SLUG=, GITHUB_WEBHOOK_SECRET=
• 可选： REDIS_URL=, KV_URL=, VERCEL_PROJECT_PRODUCTION_URL=, NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL=, VERCEL_SANDBOX_BASE_SNAPSHOT_ID=, ELEVENLABS_API_KEY=

Deploy your own copy on Vercel

在 Vercel 上部署你自己的副本

1. Fork this repo.
2. Import the repo into Vercel.
3. Neon Postgres is auto-provisioned if you use the deploy button above.
4. Generate a secret for session signing: openssl rand -base64 32 # BETTER_AUTH_SECRET
5. Add env vars in Vercel project settings: POSTGRES_URL=, BETTER_AUTH_SECRET=
6. Deploy once to get a stable production URL.
7. Create a Vercel OAuth app with callback URL: https://YOUR_DOMAIN/api/auth/callback/vercel
8. Add these env vars and redeploy: NEXT_PUBLIC_VERCEL_APP_CLIENT_ID=, VERCEL_APP_CLIENT_SECRET=
9. If you want the full GitHub-enabled coding-agent flow, create a GitHub App… (follow instructions in repo).
10. Fork 此仓库。
11. 将仓库导入 Vercel。
12. 如果使用上方的部署按钮，Neon Postgres 会自动配置。
13. 生成会话签名密钥：openssl rand -base64 32 # BETTER_AUTH_SECRET
14. 在 Vercel 项目设置中添加环境变量：POSTGRES_URL=, BETTER_AUTH_SECRET=
15. 部署一次以获取稳定的生产 URL。
16. 创建一个回调 URL 为 https://YOUR_DOMAIN/api/auth/callback/vercel 的 Vercel OAuth 应用。
17. 添加这些环境变量并重新部署：NEXT_PUBLIC_VERCEL_APP_CLIENT_ID=, VERCEL_APP_CLIENT_SECRET=
18. 如果你需要完整的 GitHub 编码智能体流程，请创建一个 GitHub App…（请遵循仓库中的说明）。

Local setup

本地设置

• Install dependencies: bun install
• Create your local env file: cp apps/web/.env.example apps/web/.env
• Fill in the required values in apps/web/.env.
• Start the app: bun run web
• 安装依赖：bun install
• 创建本地环境变量文件：cp apps/web/.env.example apps/web/.env
• 在 apps/web/.env 中填入所需值。
• 启动应用：bun run web

Useful commands

常用命令

• bun run web: run dev server
• bun run check: lint + format check
• bun run fix: lint + format fix
• bun run typecheck: typecheck all packages
• bun run ci: full CI: check, typecheck, tests, migration check
• bun run sandbox:snapshot-base: refresh sandbox base snapshot
• bun run web: 运行开发服务器
• bun run check: Lint 和格式检查
• bun run fix: Lint 和格式修复
• bun run typecheck: 所有包的类型检查
• bun run ci: 完整 CI：检查、类型检查、测试、迁移检查
• bun run sandbox:snapshot-base: 刷新沙盒基础快照