Remote development

GraphoOS is split in two processes: the window, which owns the buffer and every keystroke, and the proxy, which owns the file system, the language servers, the terminal and the plugins. When you connect to another machine only the proxy runs there — typing never waits for the network, while completion, diagnostics, search and the terminal all happen on the remote host, with its files and its tools.

SSH

From the command palette (⌘⇧P / Ctrl+Shift+P), Connect to SSH Host, then user@host (a port can follow: user@host:2222). Hosts you have used are listed; the workspace you had open there is reopened.

GraphoOS uses the ssh of your system, so everything in ~/.ssh/config applies (keys, jump hosts, aliases). On first connection it sends the proxy for the host's platform (graphoos-proxy-<os>-<arch> from the release you are running) to ~/.local/share/graphoos-<release>/proxy on Linux, ~/Library/Application Support/dev.graphoos.GraphoOS-<release>/proxy on macOS, %LOCALAPPDATA%\graphoos\GraphoOS-<release>\data\proxy on Windows, and starts it; later connections reuse it while the versions match.

Everything else is as local: the file explorer shows the remote tree, plugins run remotely (install them again there — the plugins panel installs into the remote data directory), the terminal is a shell on the host, and Run and Debug launches there.

Dev Containers

A folder with a .devcontainer/devcontainer.json (or .devcontainer.json) can be worked on inside the container it describes: Reopen in Container, from the palette, from File › Remote or from the remote button at the left of the title bar. The file is the one VS Code and GitHub Codespaces read, comments and trailing commas included.

What happens:

  1. The container comes from what the file says: image is pulled, build.dockerfile (with build.context, relative to the file's folder) is built, or dockerComposeFile with service is brought up with docker compose.
  2. The folder is mounted at workspaceFolder (/workspaces/<folder> when the file says nothing), with forwardPorts published, remoteEnv set, remoteUser as the user and runArgs added as they are.
  3. postCreateCommand runs once per container; postAttachCommand each time the editor attaches.
  4. The proxy starts inside the container, and the window opens the folder there: language servers, the terminal, search and Run and Debug use the container's tools.

Opening it again reuses the container (starting it if it was stopped). When devcontainer.json changes, the container is made again from it. The container is called graphoos-<folder>-<hash>; docker rm -f it to start from scratch. Disconnect From Remote goes back to your machine.

Docker and Podman are both used, whichever is installed (Docker Desktop, OrbStack, Colima and Podman all work), and they are found even when the editor was opened from the Finder or a desktop menu, whose PATH does not include them. The first time, pulling or building the image can take some minutes; the editor says it has started and opens the folder when the container is ready, or says what the engine answered when it fails.

Not read yet: features, mounts, customizations and the lifecycle commands other than the two above.

A proxy of your own

The proxy is installed in the container as on an SSH host. To use one you built (scripts/build_linux_proxies.sh) instead of the release's, put it in a folder as graphoos-proxy-linux-<arch> (x86_64, aarch64) and start the editor with GRAPHOOS_REMOTE_PROXY_DIR naming that folder; it is used for SSH hosts too. tools/devcontainer_smoke.py does exactly that to try the whole way against the Docker of your machine.

WSL

On Windows, Connect to WSL opens a distribution as the remote; the proxy runs inside it and the workspace is a Linux path.

What stays on your machine

Settings, keymaps, themes and the assistant's conversation; the AI providers are reached from your machine, with the remote file's content travelling through the editor.

Source: docs/remote-development.md