SSH Sessions

Scape supports saved SSH connections for remote terminal access, file browsing, and agent-driven remote command execution — all from within the Scape window.

Setting up a connection

1. Open Settings → SSH.
2. Click Add Connection.
3. Fill in the connection details:

Field	Description
Name	A display name for the connection
Host	Hostname or IP address
Port	SSH port (default 22)
Username	Remote user
Auth method	SSH Agent, Key File, or Password
Remote path	Optional default directory to open

Scape detects ~/.ssh/config aliases, so you can reference hosts defined there.

Using SSH connections

Once saved, a connection gives you:

• Terminal access — Click Connect to open a remote terminal tab in Scape.
• File browsing — Browse the remote filesystem via SFTP directly in Scape.
• Remote coding session — Click Claude to launch a coding session on the remote machine.

Remote worktrees

With a running remote coding session, you can create a git worktree on the remote host — straight from the session card. Click the worktree button on the card (or right-click it and choose Create Worktree), pick a branch, and Scape runs the create over the session's live SSH connection — no second authentication. The worktree lands in <repo>/.worktrees/<branch> on the host, and a new remote coding session opens in it.

The remote create mirrors the local pipeline: it reuses the branch if it already exists (or creates it from the repo's current HEAD), copies top-level .env files from the repo root into the new worktree, and adds .worktrees to the repo's .git/info/exclude.

Requirements — the create routes to the remote only when all of these hold; anything less fails closed with an error tab, never a silent local fallback:

• The session on that card is a live remote session (still connected at click time).
• The session's connection matches the SSH connection configured for the project.
• The project's remote repo path is absolute (paths under ~ aren't supported yet).

Session status on remote hosts

A remote coding session shows the same activity state on its card as a local one — thinking, generating, waiting for input, finished — but that state is produced on the host, by the same hook scripts Scape installs locally. Scape handles this for you: the first time you launch a remote session on a host, Scape copies its hook kit (bridge.sh, notify.sh, and a matching jq for the host's architecture) to ~/.scape/ there, and adds its statusline + hook entries to that profile's ~/.claude/settings.json (or the CLAUDE_CONFIG_DIR the session uses). Your existing keys are preserved; an existing statusline keeps working — Scape's bridge forwards to it, exactly as it does locally. Later launches only re-verify (one quick check) and re-copy a file if it changed with a Scape update.

Testing connectivity

Before saving, use the Test button to verify the connection works. Scape uses libssh2 with a 10-second timeout.

Credentials

SSH credentials (passwords and key passphrases) are stored securely in macOS Keychain. Connection metadata is persisted in SQLite.

MCP tools

Tool	Description
list_ssh_connections	List all saved SSH connections
save_ssh_connection	Create a saved connection (SSH agent, key-file, or password auth)
delete_ssh_connection	Remove a saved connection
exec_remote	Run a command on a remote host over a saved connection
create_remote_worktree	Create a git worktree in a remote repo over SSH
list_remote_worktrees	List the git worktrees in a remote repo