Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 17 additions & 31 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,8 @@ It lets you continue the same coding session from any Sandpi client.

The Web app and first-party native clients for iOS, iPadOS, Android,
OpenHarmony, Windows and macOS use the same Sandpi product UI and API. Every
client stays lightweight: the coding-agent harness, terminal, files and shared
Playwright browser live in the cloud, alongside a persistent Workspace Volume.
client stays lightweight: the coding-agent harness and terminal run in the
cloud, with files stored on a persistent Workspace Volume.
You can close your laptop, switch devices or disconnect a client without
ending your coding session.

Expand All @@ -33,10 +33,6 @@ Codex is the first supported coding agent.

<p align="center"><sub>A Codex Session alongside its persistent Workspace files.</sub></p>

![A Codex Session and shared Browser in Sandpi](./docs/images/sandpi-session-browser.png)

<p align="center"><sub>A human and coding agent working with the same cloud Browser.</sub></p>

![Environment Settings in Sandpi](./docs/images/sandpi-environment-settings.png)

<p align="center"><sub>Environment-scoped runtime, Workspace, agent and security settings.</sub></p>
Expand All @@ -51,7 +47,6 @@ Codex is the first supported coding agent.
| Durable sessions | Native session state and the Workspace live outside the browser. Refreshes, client disconnects and runtime recovery do not erase the session. |
| Focused isolation | Create one Environment per project, task or concern. Each gets its own Sandbox, Workspace, coding-agent account, network policy and credentials. |
| Multiple coding plans | Connect different Environments to different Codex/ChatGPT accounts, or keep work separated while using the same account. |
| Shared browser debugging | A human and coding agent take exclusive turns using one persistent browser profile. Take control is the only manual-input path; human control is a real headed browser without Playwright or an exposed CDP endpoint. |
| Controlled outbound access | Restrict sandbox egress by destination and inject supported credentials only into matching traffic, instead of placing service secrets in the repository or browser. |
| Workspace protection | Create manual or scheduled Workspace backups with retention and restore them through Sandbox0 Volume snapshots. |
| Encrypted persisted state | Sandbox0 encrypts persisted Environment rootfs checkpoint objects and default S0FS Workspace Volume objects at the application layer before object storage. |
Expand All @@ -64,7 +59,7 @@ Environment
├── Sandbox and persistent Workspace Volume
├── one native coding-agent harness and provider account
├── network policy and egress credentials
├── runtime resources, terminal, shared Browser and metrics
├── runtime resources, terminal and metrics
├── durable Automation Schedules and Webhooks
└── many native coding-agent Sessions
```
Expand Down Expand Up @@ -120,9 +115,9 @@ coding-agent configuration into a new or existing Sandpi Environment. See
explicit refresh feedback; fast source, GitHub-like Markdown and CSV views;
image, audio, video, PDF and PPTX previews; on-demand Monaco editing; and Git
changes
- Shared Browser with exclusive human/agent control, a full-size adaptive
read-only agent view, and one Take control path into the interactive headed
browser
- Version-matched Playwright Agent Skill materialization when the Environment
image provides the official `playwright-cli`; Sandpi does not wrap it in a
second automation protocol
- Environment terminal, runtime metrics, configurable idle pause, and manual
Sandbox pause/restart recovery controls
- Environment Schedules with one-time or human-friendly recurring timing,
Expand Down Expand Up @@ -150,10 +145,7 @@ harnesses and clients can be added as independent integrations.
- A Sandbox0 deployment API key with Sandbox and Volume access plus
`credentialsource:read`, `credentialsource:write` and
`credentialsource:delete`
- A current Sandbox0 `coding-agent` template with the official Playwright CLI,
Chromium, TigerVNC and Openbox. Sandpi retains an Xvfb/x11vnc compatibility
path for older template images. At least 2 GiB of Sandbox memory is
recommended for interactive Browser work alongside a coding agent.
- A current Sandbox0 `coding-agent` template with the official Playwright CLI
- Docker Engine with Compose v2 for the container workflow

Optional subscription quota mode also requires `usage:read`.
Expand Down Expand Up @@ -219,7 +211,7 @@ For Kubernetes deployment, see
## OpenAPI contract

The generated [OpenAPI 3.0.3 contract](./openapi.yaml) covers Sandpi's HTTP,
SSE, WebSocket and embedded Browser surfaces. Generate and verify it with:
SSE and WebSocket surfaces. Generate and verify it with:

```bash
npm run openapi:generate
Expand Down Expand Up @@ -266,22 +258,18 @@ Sandpi server ───────── PostgreSQL
Sandbox0
├── Sandbox + native Codex app-server
├── persistent Workspace Volume
├── exclusive Playwright or headed Browser transport + shared profile
├── official Playwright CLI and version-matched Agent Skill
├── terminal and runtime metrics
├── network policy and credential injection
└── Workspace snapshots
```

- Sandpi clients talk only to Sandpi. They receive neither the Sandbox0
deployment API key nor a direct Sandbox0 endpoint. For the Web app, Sandpi
authenticates and proxies the agent-owned Playwright Dashboard or the
human-owned VNC stream. The Dashboard is only a read-only screencast renderer:
Sandpi removes its controls and rejects client-side navigation, tab mutation,
input, capture and recording requests. Both transports use one persistent
profile, but only one owner is active: taking control stops Playwright and
launches a headed browser without CDP; returning control stops that browser
before Playwright resumes. Environment-local URLs shown in chat remain inert
until the user takes control.
deployment API key nor a direct Sandbox0 endpoint. Sandpi materializes the
official Playwright Agent Skill when `playwright-cli` is available, but it
does not start a browser, manage a profile, proxy a Dashboard or VNC stream,
or define a second browser-control protocol. Environment-local URLs shown in
chat remain inert until a dedicated Preview surface exists.
- Sandpi uses Sandbox0 through the official JavaScript SDK; it does not read a
Sandbox0 database, internal metering endpoint or ClickHouse credential.
- Sandbox0 owns Sandbox lifecycle, Volumes, network enforcement, credential
Expand Down Expand Up @@ -320,11 +308,9 @@ Sandbox0
- Sessions inside one Environment share one mutable Workspace and harness
account. They are not isolated checkouts. Use separate Environments when work
must not affect each other.
- Interactive Browser takeover requires the current Sandbox0 `coding-agent`
image. Older compatible images can still use scaled Xvfb/x11vnc takeover;
recreate the Environment with v0.4 or newer for a human desktop that follows
the full Browser panel size. Agent-only Playwright remains available on older
compatible images.
- Sandpi currently exposes neither an Environment Browser nor an application
Preview tab. Playwright remains available to the coding agent when the
Environment separately provides a compatible browser executable.
- Built-in administrator mode is for a trusted single-user deployment. Use OIDC
and a proper network/TLS boundary for public or multi-user deployments.
- The `/api/v1` contract is versioned but may still change between pre-1.0
Expand Down
34 changes: 14 additions & 20 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ Sandpi 客户端继续同一个 coding session。

Web 应用与 iOS、iPadOS、Android、OpenHarmony、Windows 和 macOS 第一方原生客户端
共用同一套 Sandpi 产品 UI 和 API。所有客户端都保持轻量:coding-agent harness、
终端、文件和共享 Playwright 浏览器都在云端运行,并挂载持久化 Workspace Volume。
终端运行在云端,文件则保存在持久化 Workspace Volume
你可以关闭电脑、切换设备或断开客户端,而不会结束 coding session。

目前第一个支持的 coding agent 是 Codex。
Expand All @@ -31,10 +31,6 @@ Web 应用与 iOS、iPadOS、Android、OpenHarmony、Windows 和 macOS 第一方

<p align="center"><sub>Codex Session 与持久化 Workspace 文件并排显示。</sub></p>

![Sandpi 中的 Codex Session 和共享 Browser](./docs/images/sandpi-session-browser.png)

<p align="center"><sub>Human 与 coding agent 使用同一个云端 Browser。</sub></p>

![Sandpi Environment Settings](./docs/images/sandpi-environment-settings.png)

<p align="center"><sub>Environment 级 runtime、Workspace、agent 和安全设置。</sub></p>
Expand All @@ -49,7 +45,6 @@ Web 应用与 iOS、iPadOS、Android、OpenHarmony、Windows 和 macOS 第一方
| 持久化 Session | 原生 Session 状态和 Workspace 不在浏览器里。页面刷新、客户端断线和 runtime 恢复都不会让 Session 消失。 |
| 更专注的隔离 | 可以按项目、任务或关注点创建独立 Environment。每个 Environment 都有自己的 Sandbox、Workspace、coding-agent 账号、网络策略和凭证。 |
| 多个 coding plan | 不同 Environment 可以连接不同的 Codex/ChatGPT 订阅账号;即使使用同一个账号,也可以把不同工作彼此隔离。 |
| 人与 Agent 共享浏览器 | Human 和 coding agent 使用同一个官方 Playwright browser session,共享 tab 和登录 profile。 |
| 可控的出站访问 | 按目标限制 Sandbox 出站流量,并只向匹配的请求注入受支持的凭证,避免把服务密钥放进仓库或浏览器。 |
| Workspace 防丢失 | 通过 Sandbox0 Volume snapshot 手动或定时备份 Workspace,设置保留数量并按需恢复。 |
| 持久化数据加密 | Sandbox0 在写入对象存储前,对 Environment rootfs checkpoint 对象和默认 S0FS Workspace Volume 对象做应用层加密。 |
Expand All @@ -62,7 +57,7 @@ Environment
├── Sandbox 和持久化 Workspace Volume
├── 一个原生 coding-agent harness 和 provider 账号
├── 网络策略和出站凭证
├── runtime 资源、终端、共享 Browser 和指标
├── runtime 资源、终端和指标
├── 持久化 Automation Schedules 和 Webhooks
└── 多个原生 coding-agent Session
```
Expand Down Expand Up @@ -109,8 +104,8 @@ Environment。如果多个 Session 本来就应该共享文件、工具和执行
- 以预览为主的实时 Workspace 文件浏览器,支持可调整宽度、可折叠的文件树和明确的
刷新反馈,提供快速源码、GitHub 风格 Markdown、CSV 视图,图片、音频、视频、
PDF、PPTX 预览,按需加载的 Monaco 编辑器,以及 Git 变更
- Human 与 coding agent 共用的官方 Playwright Browser,支持多 Tab、加载反馈以及
本地持久化的桌面自适应、响应式和移动端 viewport 模式
- 当 Environment image 提供官方 `playwright-cli` 时,按其版本 materialize
Playwright Agent Skill;Sandpi 不额外定义一套自动化协议
- Environment 终端、runtime 指标、可配置 idle pause,以及用于故障恢复的
Sandbox 手动 pause/restart 控制
- Environment Schedules,支持一次性或易读的周期设置、高级 Cron、IANA
Expand All @@ -135,8 +130,7 @@ Sandpi 仍处于 pre-1.0 阶段,目前只实现了 Codex harness。Web 应用
- 具备 Sandbox、Volume 访问权限以及 `credentialsource:read`、
`credentialsource:write`、`credentialsource:delete` 权限的 Sandbox0
deployment API key
- 一个包含官方 Playwright CLI 和 Chromium 的当前 Sandbox0
`coding-agent` template
- 一个包含官方 Playwright CLI 的当前 Sandbox0 `coding-agent` template
- 使用容器流程时需要 Docker Engine 和 Compose v2

可选的订阅 quota 模式还需要 `usage:read`。
Expand Down Expand Up @@ -197,8 +191,8 @@ Kubernetes 部署请参阅

## OpenAPI 契约

生成的 [OpenAPI 3.0.3 契约](./openapi.yaml) 覆盖 Sandpi 的 HTTP、SSE
WebSocket 和内置 Browser 接口。使用以下命令生成并校验:
生成的 [OpenAPI 3.0.3 契约](./openapi.yaml) 覆盖 Sandpi 的 HTTP、SSE
WebSocket 接口。使用以下命令生成并校验:

```bash
npm run openapi:generate
Expand Down Expand Up @@ -241,17 +235,17 @@ Sandpi server ───────── PostgreSQL
Sandbox0
├── Sandbox + 原生 Codex app-server
├── 持久化 Workspace Volume
├── 官方 Playwright CLI、Dashboard 和共享 profile
├── 官方 Playwright CLI 和版本匹配的 Agent Skill
├── 终端和 runtime 指标
├── 网络策略和凭证注入
└── Workspace snapshot
```

- Sandpi 客户端只与 Sandpi 通信,不会收到 Sandbox0 deployment API key,也不会直接
访问 Sandbox0 endpoint。对于 Web 应用,Sandpi 会对官方 Playwright Dashboard 的
HTTP 和 WebSocket 流量进行鉴权与代理。内置 tab 与 agent 共享同一个 Playwright
profile:human 可以在其中完成交互式登录,然后把同一份已登录 Browser 交还给
agent 继续操作。Browser 中的 loopback URL 解析到 Environment sandbox 内部
访问 Sandbox0 endpoint。当 `playwright-cli` 可用时,Sandpi 会 materialize 官方
Playwright Agent Skill,但不会启动 browser、管理 profile、代理 Dashboard/VNC,
也不会定义第二套 browser-control 协议。Environment-local URL 在专用 Preview
surface 实现前保持不可点击
- Sandpi 只通过官方 JavaScript SDK 使用 Sandbox0,不读取 Sandbox0 数据库、内部
metering endpoint 或 ClickHouse 凭证。
- Sandbox0 负责 Sandbox 生命周期、Volume、网络执行、凭证注入和 usage truth。
Expand All @@ -274,8 +268,8 @@ Sandbox0
不会在可能改变网络策略或凭证边界的情况下静默新建替代 Sandbox。
- 同一个 Environment 中的 Session 共享可变 Workspace 和 harness 账号,它们不是互相
隔离的 checkout。工作之间不能互相影响时,请创建不同 Environment。
- Browser 依赖当前 Sandbox0 `coding-agent` image。旧 Environment 需要重新创建,
才能获得 Playwright CLI 和 Chromium 依赖
- Sandpi 当前既不提供 Environment Browser,也不提供应用 Preview tab。只有在
Environment 另外提供兼容 browser executable 时,coding agent 才能使用 Playwright
- 内置管理员模式只适用于受信任的单用户部署。公开或多用户部署应使用 OIDC,并配置
正确的网络与 TLS 边界。
- `/api/v1` 已经版本化,但 pre-1.0 版本之间仍可能调整契约。
Expand Down
Loading