Connect an SSH folder

Add an SSH folder to a project to browse and edit remote files and run commands against the remote working directory.

Add a remote folder

1. Inside a project, click Add Folder (the dialog title reads Add Folder to followed by the project name).
2. Switch to the SSH tab.
3. Fill in the connection details (see table below).
4. Click Add Folder. The remote path appears in the file explorer alongside any local folders in the same project.

Connection fields

Field	Value
Host	IP address or domain of the remote server
Port	SSH port (default 22)
Username	SSH user
Auth method	Password, Public key, or SSH Agent
Password / Key passphrase	Entered in the Connect dialog when mounting the folder
Remote path	absolute path of the folder to mount

Note

A project can mix local and remote folders. Tool routing is per-folder: a tool call targets the folder of the file currently in context, local or remote.

Understand tool routing

Kora uses the selected local folder for shell commands, scripts, Git operations, system tools, and relative paths unless a remote project directory is explicitly selected for the turn. A remote folder being visible in the project does not by itself reroute unrelated tools to SSH.

Before a command runs, Kora checks that its working directory remains inside the permitted local or remote project root. Requests that resolve outside that boundary are rejected.

Open a terminal on the remote

When a connected remote folder is in the active state, an SSH terminal button appears in the file explorer. Click it to open a shell already cd-ed into the remote root. This is the same terminal panel you use for local folders; only the underlying transport changes.

Save credentials

Select Save in keychain in the Connect dialog to reuse the credential on later mounts. This Premium option stores the secret in the macOS Keychain and requires a valid Kora key. The SSH connection itself works without Kora Premium.

Troubleshooting

• Connection refused → verify the host is reachable (ping <host>), the SSH port is open, and the SSH server is running.
• Authentication fails → check username and key path. With a key, ensure the public key is listed in ~/.ssh/authorized_keys on the remote server. With SSH Agent, ensure the agent is running and the key is loaded (ssh-add -l).
• Timeout → check network connectivity and firewall rules. Some corporate networks block outbound SSH.
• Remote folder appears empty → the remote path may be wrong, or the user lacks read permission on that directory.
• Terminal button is missing → the folder must be in the connected state. Reconnect it from the Connect dialog and the button will appear.
• Save in keychain is missing → connect a valid Kora key under Settings → AI Providers → Kora.

See also: First launch for how projects and folders are organized.