[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-81830":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":11,"openIssues":13,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":14,"stars7d":14,"stars30d":14,"stars90d":14,"forks30d":14,"starsTrendScore":14,"compositeScore":15,"rankGlobal":9,"rankLanguage":9,"license":16,"archived":17,"fork":17,"defaultBranch":18,"hasWiki":19,"hasPages":17,"topics":20,"createdAt":9,"pushedAt":9,"updatedAt":21,"readmeContent":22,"aiSummary":23,"trendingCount":14,"starSnapshotCount":14,"syncStatus":12,"lastSyncTime":24,"discoverSource":25},81830,"zspark","hellangleZ\u002Fzspark","hellangleZ","codex shell",null,"Rust",29,2,11,0,1.43,"Apache License 2.0",false,"main",true,[],"2026-06-12 02:04:20","# zspark\n\nzspark is an open-source desktop and collaboration shell built on top of the open-source [Codex](https:\u002F\u002Fgithub.com\u002Fopenai\u002Fcodex) runtime.\n\nIt aims to bring the product shape of Claude Code, Claude cowork, and Codex App into a self-hostable project: a local agent desktop, native Codex sessions, skills and plugins, file artifacts, enterprise identity, and shared workspaces that teams can run on their own infrastructure.\n\n> zspark is not affiliated with OpenAI. It uses a forked\u002Fopen-source Codex runtime as the agent engine.\n\n## Why zspark exists\n\nCodex is a strong local agent runtime, but many useful product capabilities live in closed products: desktop UX, shared cowork sessions, enterprise authentication, office-oriented skills, plugin discovery, downloadable artifacts, and collaboration around a shared workspace.\n\nzspark makes those layers hackable:\n\n- Build new features without waiting for a closed desktop app to expose them.\n- Run the collaboration server yourself.\n- Connect enterprise authentication and authorization to shared workspaces.\n- Use Codex-native sessions, memory, tools, spawn behavior, skills, and plugins from an open shell.\n- Connect both Responses API providers and Chat Completions-only providers through the same desktop.\n\n## What it does\n\n- **Codex-powered desktop agent**: Electron shell around the Codex app-server runtime, without requiring Codex App.\n- **Native Codex runtime behavior**: sessions, memory, tool calls, permissions, sandbox policy, and spawn\u002Fsub-agent behavior come from Codex instead of being reimplemented in JavaScript.\n- **Skills and plugins**: discovers locally installed Codex skills\u002Fplugins and exposes them in the zspark UI, including productivity workflows such as presentations, documents, and spreadsheets when the corresponding runtime is available.\n- **File input and artifacts**: attach local files to a conversation and surface generated files back in the chat as downloadable artifacts.\n- **OpenAI Responses API support**: talks directly to providers that implement the Responses API.\n- **Chat Completions bridge**: lets Codex drive providers that only expose `\u002Fv1\u002Fchat\u002Fcompletions`, including many OpenAI-compatible model gateways and self-hosted stacks.\n- **Shared workspaces**: a self-hosted server stores shared workspaces, sessions, activity, and artifacts so multiple users can continue each other's work.\n- **Enterprise identity**: Microsoft Entra ID support is built in for controlling who can access shared workspaces. The current setup targets Azure China as well as standard Entra-shaped JWT validation.\n- **Cross-platform desktop**: macOS and Windows desktop builds are supported. The shared server is designed to run on Linux.\n\n## Repository layout\n\n```text\nzspark\u002F\n  codex-rs\u002F   Forked Codex runtime and app-server engine\n  desktop\u002F    Electron desktop shell for macOS and Windows\n  server\u002F     Self-hosted shared workspace server\n  docs\u002F       Setup notes for enterprise auth and contributors\n```\n\n## Architecture\n\n```text\nDesktop app\n  -> bundled codex binary\n  -> codex app-server\n  -> local workspace, local Codex config, skills, plugins, tools\n  -> model provider through Responses API or zspark's Chat Completions bridge\n\nShared workspace mode\n  -> zspark server\n  -> Entra ID \u002F dev identity\n  -> Postgres for workspaces, sessions, messages, artifacts\n  -> Redis + Yjs\u002FWebSocket for collaboration state\n```\n\nLocal workspaces stay private on the machine. Shared workspaces are explicitly created through the server and are visible only to principals authorized for that workspace.\n\n## Status\n\nThis is an early open-source release. The core desktop loop, provider configuration, Chat API bridge, shared workspace server, artifact upload\u002Fdownload, and Entra-based authentication path are present, but expect rough edges while the project is moving quickly.\n\nThe project is useful for builders who want a hackable Codex-based desktop today, and for teams that want to experiment with a self-hosted coworking agent surface.\n\n## Prerequisites\n\n- Git\n- Node.js 22+\n- npm 10+ or npm 11+\n- Rust stable toolchain\n- Docker and Docker Compose, only needed for the shared workspace server\n\nOn Windows, install Git for Windows, Node.js, Rust, and Docker Desktop if you plan to run the server locally. The desktop build expects the Codex binary to be built before packaging.\n\n## Quick start: desktop development\n\nClone the repository:\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FhellangleZ\u002Fzspark.git\ncd zspark\n```\n\nBuild the Codex runtime:\n\n```bash\ncd codex-rs\ncargo build --release -p codex-cli --bin codex\ncd ..\n```\n\nInstall and run the desktop app:\n\n```bash\ncd desktop\nnpm install\nnpm run dev\n```\n\nThe desktop app starts the local `codex app-server` process and connects the UI to it.\n\n## Configure a model provider\n\nOpen the desktop settings and configure:\n\n- Base URL\n- API key\n- Model name\n- Wire API: `responses` or `chat`\n\nUse `responses` for providers that support OpenAI's Responses API.\n\nUse `chat` for providers that expose Chat Completions only. zspark starts a local bridge that translates the subset Codex needs between Responses-style requests and `\u002Fv1\u002Fchat\u002Fcompletions`, including tool calls.\n\nExamples of provider families people commonly try through the chat bridge include DeepSeek-compatible gateways, Kimi-compatible gateways, vLLM, SGLang, Ollama, and other OpenAI-compatible servers. Exact model behavior still depends on the provider's tool-call and streaming support.\n\n## Build installers\n\nBuild the Codex binary first:\n\n```bash\ncd codex-rs\ncargo build --release -p codex-cli --bin codex\ncd ..\n```\n\nBuild macOS:\n\n```bash\ncd desktop\nnpm install\nnpm run build:mac\n```\n\nBuild Windows:\n\n```powershell\ncd desktop\nnpm install\nnpm run build:win\n```\n\nWindows output is written under `desktop\u002Fdist\u002F`. If Electron Builder fails while extracting signing helpers because symlink privileges are unavailable, enable Developer Mode or run the shell as Administrator.\n\n## Shared workspace server\n\nThe shared server is optional. You only need it if you want multiple users or multiple machines to collaborate in the same workspace.\n\nStart it locally:\n\n```bash\ncd server\ndocker compose up -d --build\ncurl http:\u002F\u002F127.0.0.1:8787\u002Fhealthz\n```\n\n`server\u002Fdocker-compose.yml` defaults `NODE_ENV` to `production`, so shared workspace routes require valid Entra configuration by default. For local-only development without Entra ID, start the stack with `NODE_ENV=development` and send `X-Domain-User` from a trusted local client.\n\nThe server starts:\n\n- Fastify API on port `8787`\n- Postgres for workspace\u002Fsession\u002Fartifact persistence\n- Redis for collaboration support\n- A local artifact volume for generated files, configured by `ZSPARK_ARTIFACT_STORAGE_DIR`\n\nDesktop clients should point their enterprise\u002Fshared workspace settings at the server URL, for example:\n\n```text\nhttp:\u002F\u002FYOUR_SERVER_IP:8787\n```\n\n## Entra ID setup\n\nzspark can use Microsoft Entra ID to decide who can access shared workspaces. The server validates bearer tokens, derives principal keys from the token, and checks workspace ownership or membership.\n\nImportant environment variables:\n\n```bash\nZSPARK_TENANT_ID=...\nZSPARK_CLIENT_ID=...\nZSPARK_API_SCOPE=api:\u002F\u002F\u003Cclient-id>\u002Faccess_as_user\nZSPARK_AUTHORITY=https:\u002F\u002Flogin.partner.microsoftonline.cn\u002F\u003Ctenant-id>\nZSPARK_SERVER_URL=http:\u002F\u002FYOUR_SERVER_IP:8787\n```\n\nFor Azure China setup details, see [docs\u002Fentra-setup.md](docs\u002Fentra-setup.md).\n\nFor local development without Entra ID, the server supports an `X-Domain-User` dev identity shim only when `NODE_ENV=development` and Entra variables are not configured. Do not run that shim on an internet-facing server.\n\n## Shared workspace behavior\n\nIn shared mode:\n\n- Users sign in and receive access only to workspaces they own or belong to.\n- Sessions created inside a shared workspace are listed for other authorized users.\n- Generated artifacts can be uploaded to the shared server and downloaded from the conversation.\n- A teammate can continue from a shared session, create new outputs, and make those outputs visible to the workspace.\n\nLocal recent chats remain local. Shared workspaces are intentionally shown separately in the desktop UI.\n\n## Skills, plugins, and office workflows\n\nzspark does not try to re-create every skill in the desktop layer. The goal is to let Codex use the skills\u002Fplugins it already knows how to use, while the desktop makes them visible and gives the user a better surface for files, activity, and artifacts.\n\nWhen the local Codex runtime has productivity skills available, zspark can surface workflows such as:\n\n- presentations and `.pptx` generation\n- documents and `.docx` work\n- spreadsheets and `.xlsx` work\n- browser\u002Fcomputer-use style workflows when the corresponding tools are installed\n\nGenerated files should appear as conversation artifacts where possible, including in shared workspaces.\n\n## Development commands\n\nDesktop:\n\n```bash\ncd desktop\nnpm run typecheck\nnpm test\nnpm run build\n```\n\nServer:\n\n```bash\ncd server\nnpm run typecheck\nnpm run build\n```\n\nCodex runtime:\n\n```bash\ncd codex-rs\ncargo build --release -p codex-cli --bin codex\n```\n\n## Security notes\n\n- Do not commit API keys, Entra secrets, generated user data, or local artifacts.\n- The desktop stores provider credentials locally and passes model keys to Codex through environment variables.\n- Shared workspace access depends on the server's identity configuration and workspace ACL checks.\n- Run the shared server behind your own network boundary or reverse proxy before using it with a real team.\n\n## Contributing\n\nIssues and pull requests are welcome. The most useful contributions right now are:\n\n- provider compatibility fixes for Chat Completions and Responses APIs\n- better desktop UX around files, activity, approvals, and artifacts\n- shared workspace collaboration improvements\n- enterprise auth and deployment hardening\n- skill\u002Fplugin discovery and runtime integration improvements\n\n## License\n\nSee the repository license before using zspark in production.\n","zspark 是一个基于开源 Codex 运行时构建的桌面和协作 shell。其核心功能包括提供由 Codex 驱动的本地代理、原生的 Codex 会话管理与工具调用、支持本地安装的技能和插件、文件输入输出以及与 OpenAI Responses API 和 Chat Completions 的兼容性。此外，它还具备企业身份验证、共享工作空间等特性，允许团队在自己的基础设施上运行协作环境。该项目适合需要自托管解决方案的企业或团队使用，特别是在对数据安全有较高要求且希望定制化开发新功能的场景中。","2026-06-11 04:06:52","CREATED_QUERY"]