Remote Docker development

Remote development runs one complete Studio Host per Agent on a Docker machine, while the browser and source checkout remain local. Each Compose project owns its own DSH_HOME, npm cache, pnpm store, Studio port, and fixed Preview port range. SSH forwards only those loopback ports, so Studio and Draft Preview Hosts remain unavailable directly from the LAN.

Remote prerequisite

The remote host must provide a running Docker Engine and a docker CLI that is available to non-interactive SSH sessions. Node.js and DSH are installed in the image and are not required on the remote macOS host.

Installing Docker Desktop, OrbStack, or another system runtime changes the remote machine and is intentionally outside this repository's setup script. After installation, verify the daemon from the local machine:

npm run remote -- check

The default SSH host is macmini. Override it with DSH_STUDIO_REMOTE=user@host when needed.

Start isolated Agents

Choose a unique Studio port and non-overlapping Preview range for each Agent:

npm run remote -- up agent-a 13081 13100-13115
npm run remote -- up agent-b 14081 14100-14115

up sends the current checkout as the Docker build context, starts the remote Compose project, and opens an SSH control connection that forwards the Studio and Preview ports. Open the URL printed by the command. Re-run up after source changes to rebuild the image.

Other lifecycle commands are:

npm run remote -- logs agent-a
npm run remote -- status agent-a
npm run remote -- tunnel agent-a 13081 13100-13115
npm run remote -- down agent-a

down removes the Agent's container but preserves its named volumes and Draft state. Remove those volumes explicitly only when their data is no longer needed.

Docker Desktop must support host networking because DSH intentionally listens on 127.0.0.1. The fixed Preview range is enabled only in the container through DSH_STUDIO_PREVIEW_PORT_RANGE; ordinary local Studio runs continue to pass --port 0 and use an operating-system-assigned port.

中文说明

远程开发模式会在 Docker 主机上为每个 Agent 运行一套完整 Studio Host，本机只保留 源码工作区、浏览器和 SSH 隧道。每个 Compose project 都有独立的 DSH_HOME、npm 缓存、pnpm store、Studio 端口和 Preview 端口段。DSH 仍只监听回环地址，局域网不能 直接访问这些服务。

远端只需安装并启动 Docker Engine，Node.js 和 DSH 均由镜像提供。仓库脚本不会安装 Docker Desktop、OrbStack 等系统软件。安装 Docker 后，可先运行：

npm run remote -- check

随后为每个 Agent 分配互不重叠的端口并启动：

npm run remote -- up agent-a 13081 13100-13115
npm run remote -- up agent-b 14081 14100-14115

源码改变后重新执行 up 即可在远端重建。down 只移除容器，保留该 Agent 的命名 卷和 Draft 数据。远端 Docker Desktop 需要支持 host networking，因为 DSH 会继续 绑定 127.0.0.1。