Remote hosts
Run an environment's folders, terminals, chats, agents and language servers on a Linux machine reached over SSH.
A remote host is a machine reached over SSH where an environment lives. In a remote environment, all the work happens on that machine. That covers groups and their folders, worktrees, system terminals, the file tree and git, file tabs and notes, chats with Claude Code, Codex and opencode, the tools Gateway chats run, Workers, and language servers.
You pick the host when you create the environment, and it stays fixed. An environment never spans two hosts.
Requirements
- A Linux host on x86_64 or aarch64. The app checks with
uname -smand explains when a host does not qualify. - The OpenSSH
sshbinary on this computer, on macOS, Linux and Windows alike. Your~/.ssh/config, ssh-agent, keys, ProxyJump and known_hosts work as you already set them up. - The harnesses you want to use, installed and signed in on the host. The app looks for them on the host's login-shell
PATH.
Connect
Name the host
Create an environment on an SSH destination: an alias or user@host[:port]. Host entries from ~/.ssh/config are offered as suggestions.
Sign in once
The connection opens the first time you bring up the environment after starting the app. It appears as a visible terminal where you answer passphrase, password or 2FA prompts. On Windows, the prompts show in a sign-in dialog.
Add groups
Pick root folders with the in-app folder browser, since the system's folder picker only sees this computer.
How it connects
The app keeps one long-lived control connection per host, and every file operation, command and port forward goes through it:
| Platform | Control connection |
|---|---|
| macOS and Linux | An OpenSSH ControlMaster that the sign-in opens; commands, SFTP and forwards reuse it |
| Windows | One long-lived ssh session running the host CLI in a serve mode, since Windows OpenSSH has no ControlMaster |
Each terminal uses an ssh -t session of its own. On Windows, that means a host that only accepts passwords asks again for every terminal, unless your key is loaded in ssh-agent.
Non-interactive commands never run in your shell. On connect, your login shell runs once to capture its environment; every later command runs under /bin/sh with it. Interactive terminals still start your own login shell.
Agents on the host
Agents on the host talk to the agents bus on this computer through a reverse tunnel. When the host lacks krad-ade-agents or has a different version, the app copies the right build there over SFTP. Requests through the tunnel still need the bus token. See Hosts.
Files the app keeps on the host
| Path | What |
|---|---|
~/.krad-ade/<app version>/ | Binaries, never replaced while running |
~/.krad-ade/clients/<install id>/ | Per-installation state: bus token, hook settings, env files |
~/.krad-ade/languages | Language servers, shared by package and version |
~/.krad-ade/attachments | Images pasted into chats |
Because these paths include the app version and the installation id, several computers and several app versions can share one host without clashing.
When the connection drops
Nothing keeps running on the host by itself: no tmux, no daemon. If the SSH connection is lost, the processes the app started there stop. The environment stays in the sidebar with a badge, cannot be used until it reconnects, and offers a Reconnect action. If signing in needs no prompt, the app also retries by itself, waiting longer between attempts up to a limit. Once connected again, shells start fresh and agents continue by their resume id.
Error messages tell you which step failed: resolving the name, a refused connection, a changed host key, or authentication. Timeouts for connecting, commands, requests and forwards have defaults that Settings lets you change.
WSL is not a remote host. It stays a shell choice inside a local environment.