Run ZCode on a remote server

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:

ssh exe.dev new --name=my-zcode
ssh my-zcode.exe.xyz

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

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

bash -lc 'zcode --version'

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

mkdir -p ~/project
bash -lc 'zcode -p "Reply with exactly: OK. Do not call tools." --cwd ~/project --mode plan'

Start coding#

On the VM, open a tmux session in your project folder:

tmux new -A -s zcode -c ~/project

Inside it, start ZCode's terminal UI:

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:

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 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:

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:

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 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:

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.

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