ColeMurray / background-agents
ColeMurray / background-agents
Background Agents: Open-Inspect An open-source background agents coding system inspired by Ramp’s Inspect.
背景智能体：Open-Inspect 一个受 Ramp 公司 Inspect 项目启发而开发的开源后台编程智能体系统。
Overview
Open-Inspect provides a hosted background coding agent that can:
- Work on tasks in the background while you focus on other things
- Access full development environments (Node.js, Python, git, browser automation, VS Code)
- Connect from anywhere — web UI, Slack, GitHub PRs, Linear issues, or webhooks
- Enable multiplayer sessions where multiple people can collaborate in real time
- Create PRs with proper commit attribution to the prompting user
- Run on a schedule — cron jobs, Sentry alerts, and webhook-triggered automations
- Spawn parallel sub-tasks that work in separate sandboxes simultaneously
- Use your choice of AI model — Anthropic Claude, OpenAI Codex (via ChatGPT subscription), or OpenCode Zen
概述
Open-Inspect 提供了一个托管式的后台编程智能体，具备以下能力：
- 在你专注于其他事务时，在后台处理任务
- 访问完整的开发环境（Node.js、Python、git、浏览器自动化、VS Code）
- 从任何地方连接——Web UI、Slack、GitHub PR、Linear 问题或 Webhook
- 启用多人会话，支持多人实时协作
- 创建带有正确提交归属（Commit Attribution）的 PR，归属于发起请求的用户
- 按计划运行——支持 Cron 任务、Sentry 警报和 Webhook 触发的自动化
- 生成并行子任务，在独立的沙箱中同时运行
- 使用你选择的 AI 模型——Anthropic Claude、OpenAI Codex（通过 ChatGPT 订阅）或 OpenCode Zen
Security Model (Single-Tenant Only)
Important: This system is designed for single-tenant deployment only, where all users are trusted members of the same organization with access to the same repositories.
安全模型（仅限单租户）
重要提示： 本系统仅设计用于单租户部署，即所有用户均为同一组织内受信任的成员，且拥有对相同代码仓库的访问权限。
How It Works
The system uses a shared GitHub App installation for git operations (clone, fetch, push). The control plane mints short-lived installation tokens server-side and brokers them to sandboxes through the git credential helper on demand. This means:
- All users share the same GitHub App credentials - The GitHub App must be installed on your organization’s repositories, and any user of the system can access any repo the App has access to.
- No per-user repository access validation - The system does not verify that a user has permission to access a specific repository before creating a session.
- GitHub users’ OAuth tokens are used for PR creation - For GitHub logins, PRs are created using the user’s GitHub OAuth token, ensuring proper attribution and that they can only create PRs on repos they have write access to. Users who sign in another way (e.g. Google) carry no SCM token, so their PRs fall back to the shared GitHub App bot.
工作原理
该系统使用共享的 GitHub App 安装来进行 git 操作（clone、fetch、push）。控制平面在服务器端生成短期的安装令牌，并按需通过 git 凭证助手将其代理给沙箱。这意味着：
- 所有用户共享相同的 GitHub App 凭证 - GitHub App 必须安装在你的组织仓库中，系统中的任何用户都可以访问该 App 有权访问的任何仓库。
- 无用户级仓库访问验证 - 系统在创建会话前，不会验证用户是否拥有访问特定仓库的权限。
- 使用 GitHub 用户的 OAuth 令牌创建 PR - 对于 GitHub 登录，PR 使用用户的 GitHub OAuth 令牌创建，确保正确的归属，并确保用户只能在拥有写入权限的仓库中创建 PR。通过其他方式（如 Google）登录的用户没有 SCM 令牌，因此他们的 PR 将回退到共享的 GitHub App 机器人。
Token Architecture
| Token Type | Purpose | Scope |
|---|---|---|
| GitHub App Token | Brokered git clone/fetch/push auth | All repos where App is installed |
| User OAuth Token | Create PRs, user info | Repos user has access to |
| Sandbox Auth Token | Sandbox-to-control-plane session calls | Single session |
| WebSocket Token | Real-time session auth | Single session |
令牌架构
| 令牌类型 | 用途 | 范围 |
|---|---|---|
| GitHub App 令牌 | 代理 git clone/fetch/push 认证 | 安装了 App 的所有仓库 |
| 用户 OAuth 令牌 | 创建 PR、获取用户信息 | 用户有权访问的仓库 |
| 沙箱认证令牌 | 沙箱到控制平面的会话调用 | 单个会话 |
| WebSocket 令牌 | 实时会话认证 | 单个会话 |
Why Single-Tenant Only
This architecture follows Ramp’s Inspect design, which was built for internal use where all employees are trusted and have access to company repositories. For multi-tenant deployment, you would need:
- Per-tenant GitHub App installations
- Access validation at session creation
- Tenant isolation in the data model
为什么仅限单租户
该架构遵循 Ramp 的 Inspect 设计，旨在供内部使用，即所有员工都是受信任的，且都能访问公司代码仓库。若要实现多租户部署，你需要：
- 每个租户独立的 GitHub App 安装
- 在创建会话时进行访问验证
- 数据模型中的租户隔离
Deployment Recommendations
- Deploy behind your organization’s SSO/VPN - Ensure only authorized employees can access the web interface.
- Install GitHub App only on intended repositories - The App’s installation scope defines what the system can access.
- Restrict sign-in - Configure allowed GitHub users, email domains, or active GitHub organization membership (ALLOWED_GITHUB_ORGS).
- Use GitHub’s repository selection - When installing the App, select specific repositories rather than “All repositories”.
部署建议
- 部署在组织的 SSO/VPN 之后 - 确保只有授权员工才能访问 Web 界面。
- 仅在目标仓库安装 GitHub App - App 的安装范围决定了系统可以访问的内容。
- 限制登录 - 配置允许的 GitHub 用户、电子邮件域或活跃的 GitHub 组织成员身份（ALLOWED_GITHUB_ORGS）。
- 使用 GitHub 的仓库选择功能 - 安装 App 时，选择特定仓库而不是“所有仓库”。
Key Features
Fast Startup Sessions start near-instantly through multiple layers of warming:
- Filesystem snapshots — After each prompt, sandbox state is saved; follow-up sessions restore instead of re-cloning.
- Pre-built images — Toggle per-repo (Settings > Images) or per-environment (Settings > Environments); rebuilt every 30 minutes with latest commits and dependencies.
- Proactive warming — Sandbox begins spinning up as soon as you start typing, before you hit Enter.
Multi-Repository Sessions & Environments One session can work across several repositories.
核心功能
快速启动 通过多层预热机制，会话几乎可以瞬间启动：
- 文件系统快照 — 每次提示后，沙箱状态都会被保存；后续会话会进行恢复，而不是重新克隆。
- 预构建镜像 — 可按仓库（设置 > 镜像）或按环境（设置 > 环境）切换；每 30 分钟使用最新的提交和依赖项进行重建。
- 主动预热 — 当你开始输入时，沙箱就会立即开始启动，无需等到按下回车键。
多仓库会话与环境 一个会话可以跨多个仓库工作。