WebFV
AI coding workbenches / Field guide

ZCode setup: desktop downloads, Web, TUI and model access

Separate desktop installation from developer builds, understand the unified Web/TUI command, and configure model access without assuming free usage.

By WebFV Editorial · Checked October 25, 2026 · Desktop docs v3.16.3 · sources checked October 25, 2026

What the evidence coversOfficial product docs, repository README, source configuration and notices reviewed. No software installation, provider login, purchase or model task was performed.

ZCode is an AI coding workbench with a desktop application, browser interface and terminal agent. Use the official product site for desktop downloads and zai-org/ZCode for source and development documentation. The repository contains several launch and build paths; they are not interchangeable installation recipes.

This guide was checked October 25, 2026. We reviewed public documentation and source configuration. We did not install ZCode, authenticate a provider, buy a plan or run a model task.

Choose the right distribution

What you want Starting point What not to confuse it with
A normal desktop app Installer linked by the official product site Cloning the repository and running its development scripts
TUI or a local browser interface from the unified command A prepared ZCode command-line distribution, following its accompanying documentation The standalone source Agent entry point
To modify ZCode itself The repository and its pinned development toolchain A ready-to-use desktop installer

The official Install page lists v3.16.3 desktop downloads for macOS Apple silicon and Intel, Windows x64 and ARM64, and Linux x64/ARM64 packages. The product site labels Linux downloads beta. Match the operating system, architecture and package format you actually use.

On macOS, the installation guide says to open the DMG, move ZCode to Applications and launch it. On Windows, follow the installer and open the application. On Linux, select the appropriate AppImage, DEB or RPM route described by the guide. We have not checked installer signatures, operating-system minimum versions or a particular machine's compatibility.

The repository README's update list still names v3.16.2. That does not override the newer version displayed on the product download page. Record the version actually installed when following instructions or reporting an issue.

Connect a model before expecting useful work

The official model-configuration guide documents account authorization through Continue with Z.ai or Continue with BigModel, and a separate Use API Key route. The model selector's Manage Models entry opens Model Settings.

For a compatible third-party service, the documented flow is to add a provider, choose or enter its base URL, supply its API key, add supported model IDs and enable the provider. Match the service's protocol and tool-calling capabilities; changing a model name alone does not make every endpoint compatible.

ZCode is marketed around GLM integration, but the configuration documentation also describes Anthropic/OpenAI-compatible providers. It is therefore inaccurate to describe every ZCode build as restricted to one exclusive model. An OpenAI-compatible protocol label also does not establish that OpenAI operates the endpoint.

Account login, a saved credential and a successful model request are different states. If a provider rejects a request, inspect that provider's actual error rather than assuming the desktop installation failed.

Installation does not include unlimited model usage

Client installation and model access are separate. An eligible Coding Plan, prepaid API balance or third-party provider can have different billing and usage rules. The official configuration guide distinguishes Coding Plan endpoints from general API endpoints; do not swap them simply because their hostnames look similar.

Use the endpoint documented for your account type and inspect the account's current entitlement. We make no promise of a free allowance, a particular trial, permanent model access or a final subscription price. No paid or free-trial activation was tested for this guide.

Open a workspace and make the first task inspectable

The installation guide asks you to choose a project directory as the workspace. Start with a copied or disposable project whose contents you understand, then use a task with an answer you can check. For example:

Read this project's README and list its setup prerequisites with section references. Do not edit files, install dependencies or run commands. Return the list for review.

This is an illustrative request, not a task we executed. Compare the reply with the actual file and check the recorded tool activity if the result matters. A model saying “done” is not evidence that it read the right source or completed a file operation.

The repository's project notice says the shared execution adapter is not a default operating-system sandbox. A workspace path organizes the task; it does not, by itself, isolate all file, shell or network access. Review the actual permissions and execution location before authorizing changes.

TUI and local Web use are separate from Web development

The current repository README documents these commands for an already prepared unified command-line distribution:

zcode
zcode --web
zcode --web --workspace /path/to/project --port 3030 --no-open

With that distribution, no arguments enter the TUI, while a leading --web starts the browser interface. Replace the example workspace with your own directory. The README says Web mode normally binds to loopback and prints its address; --no-open prevents automatically opening a browser window. Stop the local service with Ctrl+C.

These examples were not run here. They do not establish that a command named zcode on an existing PATH is this distribution. The README suggests command -v zcode on macOS/Linux or where.exe zcode on Windows to identify the command being launched.

By contrast, pnpm dev:web is a source-development command. It starts a development frontend and backend, normally on ports 5173 and 3030. Its existence is not evidence of a public hosted ZCode web service or a one-command consumer installation.

What the source-build prerequisites mean

At source snapshot 3c5b227, mise.toml pins Node.js 24.14.0 and pnpm 10.33.2. The source README also requires Git. These are source-development requirements, not a claim that desktop-installer users must first install that toolchain.

pnpm bootstrap prepares workspace dependencies and runtime resources; pnpm dev:desktop launches development code; pnpm bundle:desktop builds desktop packages. The README's pnpm build:zcode assembles the unified CLI archive. Its example download-domain placeholder is not an official installer URL.

The standalone CLI quickstart describes another source Agent entry point and optional SEA executables. A normal Node bundle needs its runtime and adjacent resources; a SEA executable embeds Node, while external MCP, hook or plugin programs may still need their own dependencies. Do not copy one built JavaScript file and assume it is a complete distribution.

Diagnose configuration without guessing defaults

The source CLI configuration guide separates personal provider configuration from runtime settings. Its current defaults use ~/.zcode/v2/provider_config.json for personal providers and model selection, with CLI runtime settings under ~/.zcode/cli/config.json. Alternate data directories and different builds can change those paths.

Symptom Check next
App opens but no usable model is available Provider selection, enabled models, account entitlement and authentication error
An API key is accepted into a settings field but requests fail Protocol, base URL, model ID and account type; saving is not a connection test
Web opens the wrong project or port Actual launch command and printed service address
A rebuilt CLI still reports old behavior The executable resolved on PATH and the distribution/version actually launched
Editing an old model setting has no effect Whether the current CLI already migrated to its personal provider file

The CLI quickstart documents zcode doctor --json for local version, platform and executable diagnostics. It explicitly says that diagnostic output does not prove model credentials, networking or tool calls work. We did not run that command or any repository build, dependency installation or automation for this article.