Before you start
You need an SSH host you can already access, a project directory on that host, and an installed, authenticated agent CLI there. Diri reuses your OpenSSH configuration.
Remote hosts can run Linux on x86_64 or arm64, or macOS on Apple silicon. Intel Macs are not supported as remote hosts, even though the Diri desktop app supports them.
First check that your usual SSH connection works:
ssh devboxUse your own host alias in place of devbox. Confirm the project path and agent setup on that machine. Diri does not copy your local agent credentials to it.
1. Connect the host
Open Settings → Remote → Add Host and choose SSH. Enter your host’s connection details and connect.
Diri checks the platform, uploads and verifies its small remote helper, reads the remote login environment, and tests session persistence. It does not require a preinstalled Diri service or tmux.
If setup fails, read the host’s error before retrying. Check ordinary SSH access and the supported platform list first.
2. Start a remote session
Open New Agent, choose the connected host, and select an existing project directory on that host. Choose an agent installed there and give it a task.
The agent runs on the remote machine. Diri’s local engine manages the session, while a small process on the host owns its terminal. Review the working directory before sending commands; local and remote paths are different.
3. Check persistence before disconnecting
A working SSH connection does not guarantee that the host will keep processes alive after logout. Diri reports the result of its persistence check:
native detach- The host supports detached sessions without a user supervisor.
user supervisor- Diri uses a transient supervisor already available to your user.
non-persistent- The host may end the session when the connection closes. Keep it connected or use a host with persistence support.
No mode preserves a running process across a host reboot. Persistence is about surviving a disconnect, not checkpointing the agent.
4. Return to the same session
On a host with persistence support, disconnect and reconnect to the existing session. Diri reattaches to the remote terminal and restores its current screen. Avoid launching a duplicate agent just because the connection dropped.
Try this with a disposable task before relying on it for long work. If the host reports non-persistent, or if the agent has exited, reconnecting cannot make that process continue.
For connection troubleshooting and supported behavior, see remote sessions.