Language: English | 简体中文
A browser-native AI coding assistant: the pi agent engine working inside a Succinix container environment. No installation, no backend — your browser tab is the workspace.
Sunam pairs the pi agent engine (@earendil-works/pi-agent-core + @earendil-works/pi-ai) with the Succinix container environment (@succinix/engine) inside a Chromium tab, and runs as a Cordis application: 34 built-in @sunam/plugin-* plugins plus the external Succinix engine plugin assembled by sunam.host. The engine version is generated from installed package metadata rather than copied into source. The browser connects directly to your OpenAI-compatible or Anthropic-messages model service; Sunam does not host models, accounts, or a backend.
- pi agent engine — chat, 18 capability-declared tools, subagents, automatic context compaction, resource attachments, and an
AgentDriverabstraction. - Succinix container — real Node.js / Pyodide / Lifo execution, file-RPC commands, cross-container process isolation, dual-layer snapshots, and virtual ports & services.
- Standalone settings page — Providers, Personas, and About.
- Product — Chat / Computer / Enhance / Store, three container states, and a multilingual PWA. Computer contains Computer (the display surface) / Terminal / Services / Files, with no separate Display primary entry; Enhance contains Plugins / Tools / Skills / MCP.
See FEATURES for the authoritative capability inventory and honest boundaries.
Requirements: Node.js 22, npm, a modern Chromium browser (Chrome/Edge), and an OpenAI-compatible or Anthropic-messages model service with an API key.
git clone https://github.com/CJackHwang/SunamAI.git
cd SunamAI
npm ci
npm run devThe dev server is fixed at http://localhost:7891 and serves the required cross-origin-isolation headers (COOP/COEP). Open it, go to Settings → Providers, add a provider (or pick a preset) and save your API key, then start a conversation.
Suggested workflow: pick a session and a container, describe a task, track plan / compaction / subagents in the RunBoard, and verify results in the file / terminal / services views. Complex tasks only complete after the current workspace revision passes verification.
| Layer | Choice |
|---|---|
| Application framework | @deepseek-ai/cordis@4.0.1 host + plugin registry |
| Agent engine | @earendil-works/pi-agent-core + @earendil-works/pi-ai |
| Container environment | Succinix / @succinix/engine as an external Cordis plugin over @webcontainer/api; version synchronized from package metadata |
| UI | React 19, xterm.js, react-markdown, lucide-react |
| Language & build | TypeScript (strict), Vite 8, Vitest, Playwright, Oxlint |
| Persistence | IndexedDB (sunam-v3, succinix-persist) + Local Storage (sunam_v2_*) |
| License | AGPL-3.0 |
Sunam is a pure frontend application. The browser talks directly to the model service you configure.
| Data | Stored in | Notes |
|---|---|---|
| API keys, provider/persona config, language | Local Storage (sunam_v2_*) |
Do not save personal keys on a shared device. |
| Sessions, containers, runs, events, resources, terminal history, snapshots | IndexedDB (sunam-v3 + succinix-persist) |
Clearing site data deletes everything. |
| Prompts, selected files, tool results sent to the model | Your configured provider | Sunam never uploads the whole workspace by default; the provider's own privacy / retention rules apply. |
Never commit real keys. Deployments should let each user configure their own key, or proxy through a backend you design with its own auth / audit / quota. The model service must allow CORS from your deployment origin.
WebContainers require cross-origin isolation. A production site must be HTTPS and return:
Cross-Origin-Embedder-Policy: credentialless
Cross-Origin-Opener-Policy: same-origin
The repo's vercel.json already ships these headers. For Vercel or any static host: npm run build, publish dist/, keep Node 22. After launch, at least verify container creation, file read/write, terminal boot and local-service preview.
npm run dev # dev server on port 7891
npm run typecheck # strict TypeScript
npm run lint # Oxlint
npm run test # Vitest unit & component tests
npm run test:coverage # full core coverage
npm run test:e2e # Playwright end-to-end flows
npm run test:visual # desktop / mobile visual regression
npm run test:runtime # real Succinix/WebContainer acceptance
npm run check:audit # production dependency high/critical audit
npm run build # typecheck + production build
npm run check # typecheck + lint + architecture + coverage + build + bundle
npm run check:all # check + e2e + visual + runtime + auditFreeze gates: core lines/functions/statements ≥85%, branches ≥79%; initial JS ≤108 KiB gzip,
total JS ≤568 KiB gzip (lazy runtime channels and external @succinix/engine are reported
separately, see scripts/check-bundle.mjs), production critical-path dist ≤1.95 MiB.
Playwright visual diff limit 0.2%.
The repository uses the Trellis engineering workflow. Root AGENTS.md is the unified AI engineering entry; the real project specs live in .trellis/spec/, task & research records in .trellis/tasks/, and per-developer logs in .trellis/workspace/. See CONTRIBUTING.md for the full contribution guide.
English · 中文:
- README — this document: English · 中文
- FEATURES — implemented capabilities & honest boundaries: English · 中文
- Architecture — module responsibilities, dependency boundaries, key data flows: 架构与依赖边界
- Agent runtime design — pi session, driver, IndexedDB persistence, compaction, subagents: Agent 运行设计
- Extension development guide — building capability modules / MCP / plugins: 扩展模块开发指南
- Enhancement center & store design — 增强 / 商店 / plugin center / tool library / pi + DSH ecosystem compatibility: 增强中心与商店设计方案
- Replay support — deterministic terminal-command replay boundaries: Replay 支持
- Cordis POC report — Cordis core / loader / HMR browser feasibility evidence: Cordis POC 报告
- Dependency advisory policy — production audit gate & the PWA/Workbox exception: 依赖 Advisory 策略
- Release & migration acceptance — commands, thresholds and per-phase evidence: 发布与优化冻结验收
- CHANGELOG — change history: English · 中文
- CONTRIBUTING — how to contribute: English · 中文
Sunam depends on Succinix — a browser-native Linux (WebContainer + Lifo + real Node.js) that provides the container environment, terminal execution and process/port management this project is built on. Succinix is an independent open-source project; the @succinix/engine npm package is the integration surface Sunam consumes.
GNU Affero General Public License v3.0. When you offer a modified version over a network, you must make the corresponding source available under AGPL section 13. The full terms are in the repository's LICENSE and the official GNU text. Attribution for incorporated third-party material is recorded in THIRD_PARTY_NOTICES.md.