Hosts
How krad-host reaches this computer or an SSH host, so files, commands, terminals and language servers use the same code everywhere.
An environment always belongs to a single host, either this computer or a Linux machine you name by its SSH destination. krad-host gives the rest of the app one host link with two implementations, local and SSH. krad-repo, krad-chat, krad-session, krad-lsp and krad-extensions take that link instead of touching std::fs or spawning a process for a group's files, so the same code runs on both.
What goes through the host
| Need | Local host | SSH host |
|---|---|---|
| Files | The file system | SFTP, through a hand-written synchronous SFTP v3 client |
Commands such as git -C | Child processes | Remote commands over the control connection |
| Terminals | A local PTY | Their own ssh -t sessions |
| Harness detection | PATH | The host's login-shell PATH |
| Language servers | Over stdio | Over stdio carried by ssh, with file:// URIs that use the host's paths |
| Agents bus | Loopback | A reverse port forward to the local bus |
| opencode server | Local | A local port forward to a private opencode serve on the host |
The control connection
The app talks to a host only through the system's OpenSSH ssh, so ~/.ssh/config, ssh-agent, keys, ProxyJump and known_hosts apply as you set them up. For each host there is a single control connection that stays open, created when you first bring up one of its environments after the app starts.
- macOS and Linux. Signing in opens an OpenSSH ControlMaster. Commands, SFTP and port forwards all share it, so one sign-in covers them.
- Windows. OpenSSH on Windows has no ControlMaster. The app keeps one long-lived ssh session per host running the host CLI,
krad-ade-agents, in a serve mode that multiplexes commands, terminals, the host'ssftp-serverand port forwards. A small bootstrap on the same session uploads the CLI when the host does not have this version yet. ssh asks for passwords, passphrases and host-key confirmations throughSSH_ASKPASS; the app's CLI handles those requests and the app shows them in a sign-in dialog.
Commands
When the connection opens, the app starts your login shell a single time and records its environment variables. After that, each background command is a POSIX script run by /bin/sh with those variables. Your own shell (fish, csh, nushell or any other) never has to parse the app's commands, and your profile is not re-run for each one.
Files
- Interactive file work shares one SFTP channel that keeps several requests open at once and pairs each answer to its request by id.
- A second channel carries bulk transfers.
- Operations on whole trees, such as delete, list and search, run as one host command with limits, not one round trip per file.
- Local files are copied to the host at the moment they are needed. An image pasted into a chat lands in
~/.krad-ade/attachments, and a file dropped on the remote file tree lands in the folder it was dropped on.
The bundled CLI
Each app build carries krad-ade-agents compiled as a static musl binary for linux-x86_64 and linux-aarch64. If the host has no copy, or a copy of another version, the app sends the right one over SFTP and puts its folder at the front of PATH for remote agents. The hook settings Claude Code needs are also written on the host. Python toolchain detection is built into the same CLI, so it runs on every host.
~/.krad-ade/
<app version>/bin/ binaries, never replaced while running
clients/<install id>/ bus token, hook settings, env files
languages/ language servers, shared by package and version
attachments/ files pasted into chatsLanguage servers on a host
After you agree, the app installs a server on the host by running the install steps from its manifest there. The host fetches the download itself with curl or wget and verifies the checksum. When the host has no route to the download, this computer fetches and verifies it instead and copies it across on the bulk channel.
Recovery
- Connecting, commands, requests and forwards all time out. Each has a default, and Settings lets you change them.
- An error says which step failed: the name did not resolve, the connection was refused, the host key changed, or authentication failed.
- After a drop, the app retries by itself, waiting a little longer each time up to a limit, provided no sign-in prompt is needed. If one is, the environment's badge waits for you.
- There is no remote daemon. The host's processes end with the connection, and on reconnect shells are relaunched and agents resume by their resume id.
- Logs are written through
tracingand leave out secrets and file contents.
Not hosts
WSL is a shell inside a local environment, reached through wsl.exe, not a host. Hosts that are not Linux on x86_64 or aarch64 are refused.