Remote Development

ZCode remote development lets you run a workspace inside a remote host or a local container. After the connection succeeds, file reads, terminal commands, Git operations, and ZCode Agent execution happen in the target environment; the desktop client still handles your account, model configuration, task entry points, and interface.

This is useful for projects that need a server, an internal machine, a GPU development box, or a containerized environment. You keep the ZCode desktop experience on your machine while the Agent directly accesses the code, dependencies, and command line in the target environment.

When To Use It

• Project code and dependencies only exist on a remote Linux server.
• You need GPU resources, internal services, databases, or a dedicated toolchain on a remote machine.
• You want to isolate dependencies inside a local Docker container instead of changing your host environment.
• Your local machine is not the right place to run the project, but you still want ZCode Agent to develop, debug, and verify it.

Before Connecting

Before using SSH, confirm that:

• Your machine can reach the target host through SSH.
• You know the host address, port, and username.
• The target host supports password login, or you have the private key file and optional key passphrase ready.
• If you use ~/.ssh/config, you can run ssh <HostAlias> in a terminal first to confirm the alias works.

Before using Docker, confirm that:

• The local Docker daemon is running.
• The target container has already started.
• The container can access the project directory and has the shell, Git, Node.js, or other toolchain required by the project.
• If the container list does not show the target container, you can still enter the container name or container ID manually.

Open A Remote Connection From ZCode

In the ZCode main window, click the current project name in the lower-right corner to open the workspace menu, then choose Remote Connection. The wizard first asks you to choose the connection type: SSH connects to a remote host, while Docker connects to a local container.

After choosing the type, click Next to open the corresponding configuration page. The left side of the wizard shows the current steps: choose type, fill configuration, connecting, and choose directory. If the connection takes a while, use the log to understand the current progress.

Connect To A Remote Host With SSH

The SSH page is where you enter remote host connection details.

Configure it in this order:

1. SSH config alias (optional): ZCode reads available aliases from your local SSH config. Selecting an alias fills the host, port, username, and private key path automatically. If you do not use an alias, keep "Do not use alias" and fill the fields manually.
2. Host: enter the remote host address or IP, such as 192.168.1.100 or dev.example.com.
3. Port: the default is 22. If the server uses a bastion port or custom port, enter the real port.
4. Username: enter the remote login user, such as root, ubuntu, or deploy.
5. Authentication: choose Password or Private key. Passwords are not written to connection history. For private key authentication, enter the key file path; if the key has a passphrase, enter that too.
6. Resource download method: on first connection, ZCode prepares the components required on the remote side. Download locally then upload lets the desktop download resources and upload them to the remote host. Download on remote server lets the remote host access the ZCode CDN directly, which can reduce upload time, but the remote host must have network access plus download, extraction, and checksum tools.

After filling the form, click Start connection. When the connection succeeds, ZCode moves to remote directory selection, where you choose the directory to open as the workspace.

Connect To A Local Container With Docker

The Docker page is where you choose or enter a running local container.

If ZCode detects running containers, choose one from Select a running container. Opening the dropdown refreshes the container list so you do not pick a stopped container.

If the list is empty, or Docker does not return the full list, manually enter the container name or container ID in the Container field, for example:

zcode-dev
7f3a8c2d9e10

Docker connections use docker exec and docker cp to enter the local container. This is best for development containers that already have the project environment prepared. If the container has not started, run docker ps in a terminal first and confirm it is visible.

First Connection And Logs

After you click Start connection, the wizard enters the Connecting page. It shows a live connection log, including environment checks, remote resource preparation, runtime initialization, and failure reasons.

The first connection is usually slower than later ones because ZCode needs to prepare the remote service and Agent runtime in the target environment. Later connections reuse prepared resources unless the version changes or resources are missing.

If the connection fails, the bottom of the page shows an error summary. Click Back to adjust configuration and retry, or click Feedback so ZCode can include the current connection log and screenshot for troubleshooting.

After Entering A Remote Workspace

After the connection succeeds and you choose a directory, ZCode opens that directory as a remote workspace. You can use it much like a local workspace:

• View and edit remote files in the file tree.
• Ask the Agent to read code, modify files, run tests, or execute commands.
• Use the terminal to operate the shell inside the remote host or container.
• Use Git to inspect status, branches, and commits.
• Re-enter or reconnect recent remote workspaces from the workspace list.

Project files, command execution, and the Agent runtime stay in the target environment. Model providers, login accounts, global settings, and usage information remain on the desktop client.

FAQ

Why does my SSH config alias not appear?

ZCode reads aliases it can parse from your local SSH config. If the list is empty, check that ~/.ssh/config exists and is formatted correctly, then run ssh <alias> in a terminal to verify it. Even if the alias does not appear, you can still fill the host, port, username, and authentication details manually.

When should I choose "Download on remote server"?

Choose Download on remote server when the remote host can reach the ZCode CDN faster, or when uploading from your local machine is slow. The remote host needs curl or wget, tar, and at least one checksum tool such as sha256sum, shasum, or openssl. If the remote host cannot access the public internet, use Download locally then upload.

What if the Docker page shows no containers?

Run this in a terminal first:

docker ps

If no running container appears, start the container first. If the terminal shows a container but ZCode's list is empty, enter the container name or container ID manually and connect.

Where should I look when a connection fails?

Start with the last ERROR in Connection log or the error summary at the bottom of the page. Common causes include an unreachable SSH host, wrong port, wrong username or password, incorrect private key passphrase, missing download / extraction tools on the remote host, or a Docker container that is not running. If the error does not provide enough detail, click Feedback to submit the log.

Can Mobile Remote Control create a new SSH or Docker connection?

No. Mobile Remote Control controls a workspace that is already open on the desktop client. SSH and Docker remote workspaces must be created from the desktop client first; after that, your phone can use Remote Control to enter the open workspace and continue checking or sending instructions.

Next Steps