---
title: "Run ZCode on a remote server"
description: "Z.ai's open-source ZCode agent on your own exe.dev VM: GLM-5.3 with no API key, a terminal UI that keeps working after you disconnect, and desktop SSH."
url: https://exe-staging.dev/deploy/zcode
category: "AI agents"
updated: 2026-11-02
---
# Run ZCode on a remote server
Z.ai's coding agent on a Linux VM that stays on, with GLM-5.3 and no key.
- **Software:** ZCode (https://zcode.z.ai/)
- **Source:** https://github.com/zai-org/ZCode
- **License:** Apache-2.0
- **Time:** 20 minutes
- **Example VM name:** `my-zcode` (yours will differ; on the VM, `hostname` prints it)
- **Machine-readable:** https://exe-staging.dev/deploy/zcode/manifest.json
## What you get
- `zcode` 3.17.1 on the VM, built from the v3.17.1 tag
- ZCode set to GLM-5.3 through exe.dev's LLM integration, with no Z.ai key on the VM
- A project folder at `~/project` on persistent disk
- A `zcode` tmux session that survives disconnects
Running on the VM:
- **ZCode 3.17.1**: the `zcode` command, built from Z.ai's tagged source, on Node.js 24, data in `~/.zcode`
- **exe.dev LLM integration**: GLM-5.3 and GLM-5.3 Flash, served by Fireworks, with no key on the VM
- **Your project**, data in `~/project`
- **tmux**: keeps ZCode running when you disconnect
How it is reached:
- ssh my-zcode.exe.xyz (private): ZCode's terminal UI, in tmux
- exedev@my-zcode.exe.xyz, port 22 (private): ZCode desktop's Remote Development, with your exe.dev SSH key
## Deploy with Shelley
Open https://exe-staging.dev/new?prompt=Set%20up%20ZCode%20on%20this%20VM%20by%20following%20the%20exe.dev%20recipe%20at%20https%3A%2F%2Fexe-staging.dev%2Fdeploy%2Fzcode.md%20from%20top%20to%20bottom.%0A%0AThe%20recipe%27s%20example%20VM%20name%20is%20my-zcode.%20This%20VM%27s%20name%20is%20the%20output%20of%20%60hostname%60%3A%20use%20it%20wherever%20the%20recipe%20writes%20my-zcode.%20Skip%20the%20step%20that%20creates%20the%20VM%3B%20you%20are%20on%20it.%0A%0AYou%20are%20done%20when%20all%20of%20these%20are%20true.%20Check%20each%20one%20yourself%3A%0A-%20%60zcode%60%203.17.1%20on%20the%20VM%2C%20built%20from%20the%20v3.17.1%20tag%0A-%20ZCode%20set%20to%20GLM-5.3%20through%20exe.dev%27s%20LLM%20integration%2C%20with%20no%20Z.ai%20key%20on%20the%20VM%0A-%20A%20project%20folder%20at%20%60~%2Fproject%60%20on%20persistent%20disk%0A-%20A%20%60zcode%60%20tmux%20session%20that%20survives%20disconnects%0A%0ARun%20%22Install%20ZCode%20by%20hand%22%2C%20skipping%20VM%20creation%20and%20SSH.%20The%20build%0Atakes%20several%20minutes%3A%20run%20long%20steps%20in%20tmux%20or%20in%20the%20background%20and%0Await%20for%20them%3B%20don%27t%20cut%20them%20short.%20If%0A%60~%2F.zcode%2Fv2%2Fprovider_config.json%60%20already%20exists%2C%20keep%20a%20copy%20as%0A%60provider_config.json.bak%60%20before%20writing%20the%20new%20one%2C%20and%20tell%20the%0Aowner.%20Create%20the%20tmux%20session%20detached%20%28%60tmux%20new%20-d%20-s%20zcode%20-c%0A~%2Fproject%60%29%20rather%20than%20attaching%2C%20and%20reuse%20it%20if%20it%20exists.%20Don%27t%20start%0Ainteractive%20%60zcode%60%20and%20don%27t%20run%20%60zcode%20--web%60.%20Verify%20with%20the%0A%60zcode%20-p%60%20command%20in%20that%20section%2C%20expecting%20%60OK%60%2C%20and%20with%0A%60tmux%20has-session%20-t%20zcode%60.%20Finish%20with%20the%20SSH%20command%20from%20%22Take%20a%0Abreak%22%2C%20using%20this%20VM%27s%20name%2C%20and%20tell%20the%20owner%20to%20run%20%60zcode%60%20inside%0Athe%20tmux%20session.%0A%0AFinish%20with%20the%20URLs%20I%20should%20open.%0A to create a VM whose agent, Shelley, follows this recipe. From a terminal:
```sh
curl -fsSL https://exe-staging.dev/deploy/zcode/prompt.txt | ssh exe.dev new --prompt=/dev/stdin
```
Or follow the steps below by hand.
[ZCode](https://zcode.z.ai/) is Z.ai's open-source coding agent: a desktop
app, a terminal UI and a web mode, built around Z.ai's GLM models. On an
exe.dev VM it gets a Linux machine that stays on, with your code on
persistent disk, and GLM-5.3 through exe.dev's
[LLM integration](/docs/integrations-llm): no Z.ai account or API key
needed, with usage billed to your exe.dev account.
You can drive it two ways. SSH in and run ZCode's terminal UI in tmux, so it
keeps working when your laptop sleeps. Or, if you use ZCode desktop, open the
VM as a remote workspace: the agent, terminal and files live on the VM and
the desktop app is the window onto them.
> [!NOTE]
> ZCode moves fast: 3.17.1 shipped on October 30, 2026. Z.ai doesn't publish
> a Linux build of the `zcode` command, so this page builds the tagged
> source on the VM. That takes about 10 minutes, once.
## Create the VM
On your computer, create a VM and connect. Pick any free name; if you've
already clicked Deploy or have a VM, skip the first command and use its name:
```bash
ssh exe.dev new --name=my-zcode
ssh my-zcode.exe.xyz
```
Install ZCode by hand
### Install Node.js 24 and pnpm
ZCode needs Node.js 24 or newer, and the VM's Node.js is older. On the VM,
install it from NodeSource, with the pnpm version ZCode's repository pins:
```bash
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo npm install -g pnpm@10.33.2
node --version
```
Expect `v24.` followed by a minor version.
### Build and install ZCode
Fetch the v3.17.1 release and build the `zcode` command. `pnpm install`
downloads about 3 GB of dependencies; `pnpm typecheck` builds a shared
package that the packaging step needs (ZCode's
[packaging notes](https://github.com/zai-org/ZCode/blob/main/specs/zcode-unified-distribution.md)
describe this). Both build steps need more memory than Node.js allows by
default on a VM with 8 GB, so raise the limit for this shell first:
```bash
git clone --depth 1 --branch v3.17.1 https://github.com/zai-org/ZCode ~/src/zcode
cd ~/src/zcode
pnpm install
export NODE_OPTIONS=--max-old-space-size=6144
pnpm typecheck
pnpm build:zcode --base-url "file://$HOME/src/zcode/dist/zcode/"
sh dist/zcode/install.sh
```
On a new VM with 2 CPUs this takes about 10 minutes and leaves about 10 GB
of the disk used. The installer puts ZCode in `~/.zcode/runtime` and the `zcode` command in
`~/.local/bin`. Check it from a fresh login shell:
```bash
bash -lc 'zcode --version'
```
Expect `3.17.1`.
### Point ZCode at GLM-5.3
Tell ZCode to use GLM-5.3 and GLM-5.3 Flash through exe.dev's LLM
integration. The VM needs no key: exe.dev adds credentials on the way out,
and ZCode only insists that the key field isn't empty.
```bash
mkdir -p ~/.zcode/v2
cat > ~/.zcode/v2/provider_config.json <<'EOF'
{
"schemaVersion": 1,
"config": {
"providerConfigRules": {
"providerRules": [
{
"providerId": "exe-dev",
"providerName": "exe.dev",
"config": {
"group": "standard-personal",
"access": { "type": "api-key", "apiKey": "not-needed" },
"api": {
"type": "openai-chat-completions",
"baseUrl": "https://llm.int.exe.xyz/fireworks/inference/v1"
},
"personalModelIds": [
"accounts/fireworks/models/glm-5p3",
"accounts/fireworks/models/glm-5p3-flash"
]
}
}
]
},
"modelConfigRules": { "providerModelRules": [], "manualProviderModelRules": [] },
"defaultModelSelection": {
"providerId": "exe-dev",
"modelId": "accounts/fireworks/models/glm-5p3"
}
}
}
EOF
```
Make a project folder and ask GLM-5.3 a question without opening the
terminal UI. `--mode plan` keeps it from changing anything:
```bash
mkdir -p ~/project
bash -lc 'zcode -p "Reply with exactly: OK. Do not call tools." --cwd ~/project --mode plan'
```
Expect `OK.`. A warning about a built-in provider refresh
(`ZCode Built-in 刷新失败`) is harmless: it's ZCode's own Z.ai provider
list, which you aren't using.
## Start coding
On the VM, open a tmux session in your project folder:
```bash
tmux new -A -s zcode -c ~/project
```
Inside it, start ZCode's terminal UI:
```bash
zcode
```
The prompt box shows `accounts/fireworks/models/glm-5p3 exe-dev`. Give it a
small task, for example:
> Build a tiny website for a bakery that only sells one kind of bread.
ZCode starts in Build mode and asks before it writes a file or runs a
command: pick **Allow once** or **Always allow in this project** with the
arrow keys and Enter. Your files land in `~/project`.
## Take a break
Press **Ctrl-b**, then **d** to detach. ZCode keeps working on the VM. On
your computer, this hops back in:
```bash
ssh -t my-zcode.exe.xyz 'tmux new -A -s zcode -c ~/project'
```
A VM restart ends the tmux session but not your files or ZCode's saved
sessions in `~/.zcode`. Reopen the tmux session and run `zcode --continue`
to resume the latest conversation in that folder, or type `/resume` in ZCode
with a session ID (`sess_…`) for an older one.
For scripts and cron jobs, `zcode -p "…" --cwd ~/project` runs one prompt
without the terminal UI. It defaults to `--mode yolo`, which allows every
tool without asking; pass `--mode plan` for read-only questions.
## Open the VM from ZCode desktop
If you use ZCode desktop, its
[Remote Development](https://zcode.z.ai/en/docs/remote-development)
opens the VM as a remote workspace. File reads, terminal commands, Git and
the agent run on the VM; your account, model settings and the window stay in
the desktop app.
In ZCode desktop, click **+** next to **Projects**, choose **Remote
Connection**, then **SSH**, and fill in:
- **Host**: `my-zcode.exe.xyz`
- **Port**: `22`
- **Username**: `exedev`
- **Authentication**: **Private key**, with the key you use for exe.dev
(such as `~/.ssh/id_ed25519`)
On the first connection ZCode installs its server in `~/.zcode/server` on the
VM. Either resource download method works: the VM has `curl`, `tar` and
`sha256sum`. Then choose `/home/exedev/project` as the workspace (if you
skipped the build, create it first with `ssh my-zcode.exe.xyz mkdir -p
project`).
This doesn't need the build above. Models come from the desktop app's own
settings, so the exe.dev LLM integration isn't used here.
> [!NOTE]
> We couldn't run ZCode desktop for this page, so this section follows
> Z.ai's docs and ZCode's source rather than a test. The SSH settings are the
> same ones any SSH client uses for an exe.dev VM. ZCode's own SSH client
> ignores `ProxyJump` and `ProxyCommand` in `~/.ssh/config`, which exe.dev
> doesn't need.
## Use your Z.ai plan instead
To use your Z.ai account, sign in on the VM:
```bash
zcode login zai --no-browser
```
It prints a link; open it on your computer and approve, and ZCode finishes
signing in by itself. Use `zcode login bigmodel --no-browser` for a
BigModel account. This keeps a Z.ai login on the VM, in `~/.zcode`.
To keep a Z.ai API key off the VM entirely, let exe.dev hold it. On your
computer, paste the key when the command waits for input, then press Enter
and Ctrl-D:
```bash
ssh exe.dev integrations add http-proxy --name zai --target https://api.z.ai --bearer=- --attach vm:my-zcode
```
Then, on the VM, edit `~/.zcode/v2/provider_config.json` from "Point ZCode
at GLM-5.3" in three places: set `baseUrl` to the integration,
`https://zai.int.exe.xyz/api/coding/paas/v4` for the GLM Coding Plan or
`https://zai.int.exe.xyz/api/paas/v4` for pay-as-you-go keys; replace the
two `personalModelIds` with Z.ai's names, `glm-5.3` and `glm-5.3-flash`; and
set `modelId` under `defaultModelSelection` to `glm-5.3`. Leave `apiKey` as
it is: exe.dev adds your key on the way out. We checked that both paths
exist at `api.z.ai`, but didn't have a Z.ai key to test them with.
## Web mode isn't ready
The `zcode` you built also has a web mode, `zcode --web`. It listens on
`127.0.0.1` by default, and exe.dev's [HTTPS proxy](/docs/proxy) can reach
it there, so a command like this would put ZCode's web app at
`https://my-zcode.exe.xyz:3030/`, behind your exe.dev login:
```bash
zcode --web --workspace ~/project --port 3030 --no-open
```
In 3.17.1 the page loads, but on Linux the standalone server can't open a
project ("Failed to get system info") or start a task ("Failed to send");
its log shows `project.host-offline` and `project.remote-project-required`.
ZCode's packaging notes say this web build is smoke-tested without a
browser session or a model conversation. We'll update this page when a
release fixes it. Leave `--host` alone: binding to `0.0.0.0` only makes
ZCode generate an access token, which the exe.dev proxy already makes
unnecessary.
Update ZCode
Check [ZCode's releases](https://github.com/zai-org/ZCode/releases) for the
newest tag, then build it the same way. For example, for a hypothetical
v3.18.0:
```bash
cd ~/src/zcode
git fetch --depth 1 origin tag v3.18.0
git checkout v3.18.0
pnpm install
export NODE_OPTIONS=--max-old-space-size=6144
pnpm typecheck
pnpm build:zcode --base-url "file://$HOME/src/zcode/dist/zcode/"
sh dist/zcode/install.sh
```
The installer switches `~/.zcode/runtime/current` to the new release. Your
settings and sessions in `~/.zcode` stay put. Restart `zcode` in tmux to
use it.
Troubleshooting
- *`pnpm build:zcode` says `Missing @zcode/shared dist files`*: run
`pnpm typecheck` first, then the build again.
- *`pnpm typecheck` or the build stops with `JavaScript heap out of memory`*:
run `export NODE_OPTIONS=--max-old-space-size=6144` in the same shell and
repeat the step.
- *ZCode says `No available models` or `Select a model before sending a
message`*: it couldn't use `~/.zcode/v2/provider_config.json`. Compare it
with the file in "Point ZCode at GLM-5.3": the provider's settings sit
inside `config` objects, and ZCode skips a file in any other shape without
an error.
- *`zcode: command not found`*: `~/.local/bin` joins your `PATH` at login.
Open a new SSH session, or run `~/.local/bin/zcode`.
- *ZCode says Node.js is too old*: `node --version` must print `v24` or
newer; repeat "Install Node.js 24 and pnpm".
- *The model doesn't answer*: run `zcode doctor --json` on the VM, and test
the gateway with
`curl -s https://llm.int.exe.xyz/fireworks/inference/v1/models | head`.
If you edited `provider_config.json`, check that it's valid JSON with
`python3 -m json.tool ~/.zcode/v2/provider_config.json`.
- *ZCode desktop can't connect*: check `ssh exedev@my-zcode.exe.xyz true`
from the same computer, with the same key.
## Frequently asked questions
### Is there a ready-made ZCode download for Linux servers?
Not for the command line, as of ZCode 3.17.1 (October 30, 2026). Z.ai publishes desktop apps, including Linux AppImage, deb and rpm packages, but the `zcode` command with its terminal UI and web mode is something you build from the repository, as [its README](https://github.com/zai-org/ZCode#zcode-cli-distribution) describes. That's what this page does. ZCode desktop's Remote Development installs its own server on the VM, so it needs no build.
### Can I use my Z.ai account or GLM Coding Plan instead?
Yes; see "Use your Z.ai plan instead". `zcode login zai --no-browser` signs in with your Z.ai account, and an exe.dev [HTTP proxy integration](/docs/integrations-http-proxy) can hold a Z.ai API key so it never touches the VM. We tested ZCode with exe.dev's LLM integration only, not with a Z.ai account.
### Can I use ZCode in the browser?
Not usefully yet. `zcode --web` serves ZCode's web app, and exe.dev's proxy will put it behind your exe.dev login, but in ZCode 3.17.1 the standalone web mode couldn't open a project or start a task for us (the server log says `project.host-offline` and `project.remote-project-required`). Use the terminal UI or ZCode desktop's Remote Development until a release fixes it; see "Web mode isn't ready".
### Does ZCode run in a sandbox?
No. ZCode's [NOTICE](https://github.com/zai-org/ZCode/blob/main/NOTICE.md) says it has no operating-system sandbox, so the agent can do anything the `exedev` user can. The VM is the boundary: keep secrets you don't want it to use off the VM, and give it its own VM rather than the one that runs your production apps.
### How do I back up my work?
Commit and push your code. For a copy of the whole VM, including ZCode's sessions and settings in `~/.zcode`, run `ssh exe.dev cp my-zcode my-zcode-backup` on your computer (pick a free name), and connect to the copy with `ssh my-zcode-backup.exe.xyz`.
## Related
- [Run OpenCode on a remote server](https://exe-staging.dev/deploy/opencode.md): Every model, one VM, and an agent that works while your laptop sleeps.
- [Run Codex remote control on a server](https://exe-staging.dev/deploy/codex-remote-control.md): Codex on an always-on VM, steered from the ChatGPT app on your phone.
- [Run Claude Code on a remote server](https://exe-staging.dev/deploy/claude-code.md): A computer for Claude. A breather for your laptop.
- [Running Agents](https://exe-staging.dev/deploy/agents.md): Use exe.dev VMs as a sandbox
- [Host OpenClaw](https://exe-staging.dev/deploy/openclaw.md): An AI sidekick with its own computer. Your laptop can take a nap.
- [Run Codex on a remote server](https://exe-staging.dev/deploy/codex.md): A computer for Codex. An early night for your laptop.