Agents / new contributors: start with
PLAN.md(architecture + work tracker) andAGENTS.md.
ZCode is a dual-mode IDE based on VS Code OSS:
| Mode | Description |
|---|---|
| Browser | Client-side workspace: clone via isomorphic-git + same-origin /git-proxy, edit, commit |
| Remote | Password login + optional REH when server artifacts exist |
Not coder/code-server. CLI:
zcode. Source: github.com/spinupdev/zcode.
pnpm devThat is the full local setup: install deps (if needed), stage VS Code Web + themes, build packages/extensions, and serve with WebContainer COI enabled.
| URL | Role |
|---|---|
| http://127.0.0.1:5000/ | Product IDE (VS Code Web) |
| http://127.0.0.1:5000/debug/ | Debug SPA (DEV only) |
| http://127.0.0.1:5000/git-proxy | Stateless git CORS proxy |
Optional: PORT=5001 pnpm dev · pnpm dev:fast (restart without rebuild) · pnpm dev:refresh (re-fetch vscode-web/themes).
Git clone is client-side (isomorphic-git). The browser needs same-origin /git-proxy for GitHub/GitLab CORS. The SPA at /debug/ is debug dogfood and is not served in production.
pnpm dev # then open /debug/- Open http://127.0.0.1:5000/debug/ (debug SPA; product IDE is
/) - Confirm Git proxy URL is
http://127.0.0.1:5000/git-proxy(default) - Click Test proxy → green proxy ok
- Set Clone URL, e.g.
https://github.com/isomorphic-git/isomorphic-git.git - (Private repos) paste a PAT in Token (session only)
- Click Clone → progress + file tree
- Open in IDE (or confirm dialog) →
/?workspace=<id>shows the same files in VS Code Web - Edit → Save → Commit → Push (token needs write access)
Shared storage: OPFS (ZenFS, primary) with IndexedDB zcode-fs-v1 fallback (SPA + workbench).
Deep link (auto-start after proxy check):
http://127.0.0.1:5000/debug/?clone=https://github.com/org/repo.git&autoclone=1
From VS Code Web (/): Command Palette → “ZCode: Clone Repository (Browser SPA)”.
Notes: HTTPS only (no SSH in browser). Token lives in sessionStorage, not localStorage.
Real workbench from staged dist/vscode-web. Dual mode:
- Browser:
/or/?workspace=<id> - Remote:
/?mode=remote&authority=127.0.0.1:8080
See docs/vscode-web.md.
Browser mode is static SPA + stateless proxy — no durable backend required for public clones.
| Deploy | How |
|---|---|
| Local / VM | zcode web or zcode serve (both mount /git-proxy) |
| Cloudflare Pages + Worker | See deploy/cloudflare/README.md |
| Design notes | docs/hosting.md |
App default: gitProxyUrl = {origin}/git-proxy (saved in localStorage; override with ?proxy=).
NODE_ENV=development zcode web --dir apps/web/dist --port 5000 --spa-debug # DEV SPA + /git-proxy
zcode serve . --port 8080 --password secret --no-reh
zcode git-proxy --port 8787 # optional standalonepnpm test
pnpm smoke
pnpm e2e:browser # node harness: proxy + clone
pnpm e2e:playwright # browser UI: routes + SPA clone + IDE productpackages/ protocol · shell · browser-agent · server · git-proxy
apps/ cli · web
deploy/
cloudflare/git-proxy # Worker for static hosts
docker/ # container compose
docs/ design · hosting · vscode pin
Product code: TBD. vendor/vscode remains MIT (upstream).