Introduction
ZCode, published by Z.ai, was officially open-sourced on September 20, 2026. It delivers an integrated AI programming workspace, which unifies Electron desktop application, browser-based workspace, terminal UI and Agent CLI. The repository includes open-source client modules, backend services, shared UI assets and Agent runtime components. At the time of writing, the main repository version is 3.14.0, distributed under the Apache License 2.0. Full source code is publicly available, along with GitHub Release packages and tags. End users and secondary developers may build and distribute installers based on the source repository.
This article systematically breaks down the scope of this open-source release, core monorepo architecture, local source deployment workflow, packaging procedures, extension configuration, license constraints and security boundaries. It retains all original technical parameters and operational data, while reorganizing content for developer-oriented reading.
1. What Is Included in ZCode’s Open-Source Release
ZCode is not merely an isolated code model or a simple graphical client. It is a complete AI programming workspace. The official repository exposes three primary entry points for different runtime environments.
| Entry | Runtime Form | Applicable Scenarios |
|---|---|---|
| Desktop | Electron desktop application | Local projects, graphical interface operations, remote workspaces |
| Web / ZCode Command Version | Browser frontend paired with local backend | Server-side deployment, browser access, unified release bundles |
| Agent CLI | zcode command and TUI | Terminal development, script invocation, Agent runtime execution |
The repository was created on September 20, 2026. GitHub Repository API data captured on September 21, 2026 records approximately 3,521 Stars and 912 Forks. The codebase is mainly written in TypeScript. Note that these metrics are snapshot values and will keep changing as community contributions grow.
According to the root package.json, the tagged release version is 3.14.0. The license is Apache-2.0. The mise.toml file locks Node.js at version 24.14.0 and pnpm at 10.33.2. As documented in the README, Agent CLI and runtime components are already included as regular directories in the repository. There is no requirement to initialize Git submodules separately.
2. Core Architecture of ZCode
ZCode adopts a monorepo pattern to organize desktop, web, service backend, shared UI components and Agent CLI within one unified workspace. The responsibilities of each module are listed as follows:
packages/desktop: Electron Main process, Host, Renderer modules and desktop build packaging logicpackages/web: Browser-side client implementationpackages/server: HTTP and WebSocket services for remote connectionspackages/ui: Reusable React components, custom Hooks and Zustand state managementpackages/provider: Common interfaces and Node-side capabilities for model Providersapps/zcode-cli: Agent CLI, TUI, runtime and tool implementations
This architectural design enables shared Agent capabilities among desktop, web and terminal editions. Still, permission sets, file locations, authentication rules and network environments differ between the three frontends. The official NOTICE.md highlights an important reminder: commands triggered within web or remote workspaces may execute on the service host, SSH host, WSL or containers. Developers cannot judge the execution environment purely from the visible frontend device.
3. Local Source Deployment
Source-based deployment targets secondary development and auditing users. Users who only want to use the product directly should wait for or download official signed release artifacts.
3.1 Environment Preparation
Before cloning the repository, developers need to install Git, Node.js 24.14.0 and pnpm 10.33.2.
pnpm bootstrap installs workspace dependencies, prepares local desktop resource assets and runs build:bootstrap. By default, this command skips remote resource preparation and fits local desktop development. If SSH or WSL remote functions are required, run the extended bootstrap script.
Dependency installation and build scripts may run native modules and lifecycle hooks. When handling untrusted branches or pull requests, build tasks should run inside isolated accounts, containers or disposable environments.
3.2 Launch Desktop Version
Two modes are available for desktop development: production configuration and test environment.
To isolate development data, specify a custom data base directory with environment variables.
This variable directs application data storage to the .zcode/ folder under the assigned path, preventing development conversation data from polluting regular configurations.
3.3 Launch Web Version
Web development mode starts frontend and backend services concurrently.
Default service addresses:
- Web development server: http://localhost:5173
- Backend service: http://localhost:3030
Specify the backend workspace by absolute project path.
Requests under /ws and common /api routes are proxied to the local backend. Development services should never be exposed directly to public networks without authentication.
4. Terminal Version and Unified zcode Command
The ZCode command release package unifies TUI, Web and Agent functions under a single command. Invoking without parameters opens the terminal interactive interface, while --web launches the browser workspace.
Web mode listens to 127.0.0.1 by default and automatically selects available ports. Local listening disables public access by default. When using --host 0.0.0.0 to listen on non-local addresses, the official implementation generates access tokens automatically. Even with token protection, cross-machine deployment requires TLS, host firewall and reverse proxy access controls.
To launch a general HTTP service, use ZCODE_SERVER_AUTH_TOKEN to configure authentication for API and WebSocket connections. Do not use --no-token in public network environments for convenience.
5. Build Release Packages
Desktop builds and command-line packages use separate build entry points. Output artifacts cannot substitute each other.
5.1 Desktop Application Build
--os supports mac, win and linux. --arch covers x64 and arm64. Actual signing requires certificates and tooling corresponding to the target platform. Local builds are not equivalent to officially trusted signed releases.
5.2 Command-Line Release Build
pnpm build:zcode compiles CLI/TUI, backend and Web assets, assembling a unified runnable package.
https://downloads.example.com/zcode is a placeholder address and must be replaced with a real hosting URL before release. Output assets are placed inside dist/zcode, including:
releases/<version>/zcode-<version>.tar.gzreleases/<version>/sha256.txtlatest.jsoninstall.sh
The installation script places runtime files under ~/.zcode/runtime and creates the zcode command inside ~/.local/bin. The build process will not automatically update the system PATH. Existing commands with identical names will not be overwritten. Use command -v zcode on Linux or where.exe zcode on Windows to verify installation entries.
6. Provider, Plugin and MCP Configuration Notes
ZCode supports Provider configuration, Plugins, Skills, Hooks and MCP extensions. These extensions may read files, spawn processes, access the network or send parameters to remote services. Users should audit permission risks before enabling any extension.
| Environment Variable | Purpose |
|---|---|
| ZCODE_DATA_BASE_DIR | Application data root directory |
| ZCODE_SERVER_WORKSPACE | Backend workspace path |
| ZCODE_BUILTIN_PROVIDER_CONFIG_FILE | Local Provider configuration file path |
| ZCODE_DIST_BASE_URL | Base download URL for command installation packages |
Model endpoints, keys and MCP servers can be defined inside the base configuration or secrets file. Before formal release, users can connect mainstream large model endpoints via custom Provider setup.
The official NOTICE.md clarifies that workspace-level MCP servers are included within automatic connection scopes. Stdio servers start locally or on remote hosts. HTTP/SSE servers send requests to remote endpoints. Before activating plugins or MCP servers, developers must review command definitions, environment variables, authentication tokens, OAuth scopes and tool permissions.
Multi-model production deployments often need centralized traffic management for different model endpoints. An API gateway helps normalize request format, authentication logging and traffic throttling for heterogeneous LLM services. 4sapi, as an API gateway, can simplify unified access control for multi-provider agent pipelines.
7. License and Usage Rights
Apache License 2.0 permits usage, modification and distribution of source code and derivative works. Redistribution must retain license text, modification statements, copyright and attribution information specified in NOTICE files.
Three layers of license review are required:
- Apache-2.0 terms of the primary ZCode repository
- Licenses of third-party dependencies recorded inside
package.json - Licenses of actual used models, plugins, MCP servers and online services
Open-source client code does not mean all model invocations are free of charge, nor does it imply all built-in online services can be privatized. The repository source controls client-side behaviors, but cannot cover external gateway or backend service implementations.
8. Security Boundaries and Common Questions
Q: Does open sourcing mean ZCode includes model weights?
A: No. ZCode is an Agent workspace and runtime framework. Actual model capabilities are supplied by external Providers or remote services. ZCode cannot be equated with a standalone code model.
Q: Why does the project fail to launch after pnpm bootstrap?
A: First verify Node.js version 24.14.0 and pnpm 10.33.2. Inspect dependency build logs and desktop runtime resources. Remote workspace functions require running pnpm bootstrap:with-remote.
Q: Is version 3.14.0 a stable Release?
A: As of September 21, 2026, GitHub Releases endpoint returns HTTP 404, and the tag list is empty. Version 3.14.0 is defined inside package.json from source code, not an official GitHub Release tag.
Q: Can ZCode Web run within local area networks?
A: Listening to 0.0.0.0 is possible, but developers must protect endpoint tokens, deploy TLS encryption, firewalls and access controls. Workspace files and Agent tool operations run within the service host permission scope.
Q: Can the “completed” status shown by Agent be trusted?
A: This status is only a prompt. Official requirements mandate cross-checking file changes, command exit status, tool return values and test validation. Critical operations must retain recoverable backups.
9. Should Teams Deploy ZCode Now?
Teams requiring custom Provider integration, plugin and MCP extensions can start source evaluation immediately. Teams that want finished graphical installers should wait for official Release, upgrade guides and compatibility testing.
The core value of ZCode’s open-source release is bundling frontend UI, web services, TUI, Agent CLI and shared runtime modules into one maintainable monorepo, rather than simply releasing isolated frontend code. Based on Z.ai’s official announcement, this article references the September 20, 2026 NOTICE and README. The project is in active development before formal GitHub Release tagging. Functional boundaries and permission rules may be adjusted.
Extended Resources
- ZCode official repository: https://github.com/zai-org/ZCode
- Apache License 2.0: https://github.com/zai-org/ZCode/blob/main/LICENSE
International access: https://4sapi.com
Domestic access: https://4sapi.cn
