Remote workspaces (SSH)

Experimental

Remote workspaces are experimental. Open Settings → Experimental and enable Remote workspaces before creating one. Enabling the setting makes remote workspace controls available; it does not connect to a host. Existing remote workspaces remain available if you later disable the setting.

A remote SSH workspace keeps your checkout and development tools on another machine while the app runs on your Mac. The remote host can be Linux or another Mac. Git operations, terminals, and supported agent sessions run beside the remote files instead of copying the repository to your Mac.

Before you start

You need:

• An SSH destination your Mac can reach without a background password prompt.
• Git installed on the remote host.
• A Linux or macOS host with an x86_64 or ARM64 processor.
• Outbound HTTPS access from the remote host.
• Each coding-agent CLI you plan to use installed and authenticated on the host.

Supported remote hosts

The app remains macOS-only. The SSH host can be Linux or macOS.

Linux support targets Ubuntu with OpenSSH, Git, and a POSIX shell. Other Linux distributions may work when they provide compatible tools, but they are not yet part of the supported baseline.

Connecting this Mac to another Mac is supported. OpenSSH, Git, and a POSIX shell are enough to browse, run terminals, and work with Git. The managed sc helper has extra host requirements, described below.

For a custom user, port, key, or other SSH option, define an alias in ~/.ssh/config:

Copy

Host buildbox
  HostName 203.0.113.10
  User dev
  Port 2222
  IdentityFile ~/.ssh/buildbox_ed25519

Confirm that ssh buildbox works in macOS Terminal before using buildbox in the app.

Create a remote workspace

1. Select New Workspace.
2. Choose Remote Machine.
3. Enter a workspace name and SSH target. The target can be an SSH alias or a destination such as dev@example.com.
4. Leave the super.engineering CLI option enabled for live updates, agent notifications, and automatic branch naming.
5. Select Create.

The app saves the workspace and tests the connection. If setup is incomplete, open the workspace settings and finish it under Remote SSH.

Set up the connection

Under Settings → Workspace → Remote SSH:

1. Select Test Connection.
2. If authentication fails, configure an existing key through your SSH agent or macOS Keychain, or select Install SSH key.
3. Select Install / Update CLI if the managed CLI is missing or incompatible.
4. Keep Keep CLI up to date automatically enabled to repair missing or outdated installations.

Background operations never show an SSH password prompt, so passwordless key authentication is required for reliable updates.

What the app installs

If you select Install SSH key, the app creates a dedicated key in your Mac’s ~/.ssh directory, adds its IdentityFile entry to your SSH config, and adds the public key to the remote user’s ~/.ssh/authorized_keys.

The app keeps the current managed CLI, any version still in use, and the two newest inactive versions. It removes older inactive versions.

Add a remote project

Select the + beside Projects, browse the remote host, and choose the project folder. The app discovers its existing Git worktrees and displays them in the sidebar.

Each remote workspace belongs to one SSH connection. A remote project cannot be moved into a local workspace or to a different SSH workspace; add it from the destination workspace instead.

Delete remote items

• Deleting a workspace or removing a project removes it from the app. It does not delete the remote repository.
• Deleting a worktree removes that checkout from the remote host. The app may also delete its branch or remote-tracking references, according to your cleanup settings.
• Remote worktree deletion currently skips pre-cleanup and post-cleanup scripts.

What runs where

Task	Location
Git, worktree, diff, terminal, and supported agent commands	Remote host
App UI, settings, and session metadata	Your Mac
Structured PR or MR actions through gh or glab	Your Mac by default
Agent-driven PR or MR creation	Remote host when its forge CLI is installed and authenticated

You do not need to copy forge credentials to the host for the app’s structured PR or MR flow. See Supported forges for local gh and glab setup.

Credentials and network access

Operation	Authentication location
SSH connection	Your Mac’s SSH config, key, or agent
Git fetch and push	Remote host
Structured PR or MR creation	Your Mac’s gh or glab
Agent-driven PR or MR creation	Remote host’s gh or glab
Coding-agent requests	Remote provider CLI; configured provider environment values are forwarded over SSH

Agent API calls, Git fetches and pushes, package installation, and host-side forge commands originate on the remote host. Configure its DNS, proxy, and firewall rules to permit those operations.

Managed CLI

The managed sc CLI streams Git changes to the app and supports hooks, notifications, and automatic branch naming. The app can install and update it after you approve remote setup. It ships an OS-matched helper for Linux and macOS on both ARM64 and x86_64.

Installing it on Linux needs util-linux flock and the ability to run executables through /proc/self/fd. On a remote Mac it needs the system lockf command and a home directory that can execute a pinned hard link.

Without the managed CLI, remote browsing and terminals remain available, but live Git status, hooks, notifications, and automatic branch naming are unavailable.

Coding agents

Chat UI launches the provider through a non-interactive SSH session. A command available in your interactive shell may be absent from that session’s PATH. Check discovery from your Mac:

Copy

ssh <target> 'command -v claude'

Replace claude with the command for your selected provider.

SSH workspaces always run Claude Code through the structured claude -p transport. The interactive Claude setting applies only to local workspaces.

Full agent integration also requires SSH forwarding so provider hooks and managed app commands can reach your Mac.

Connection indicators

The app shows an indicator only when the remote connection needs attention:

• No indicator means the connection is healthy.
• A yellow dot means the host is unreachable.
• Install SSH key means background key authentication failed.
• Dimmed Git counts mean the displayed remote data is stale.

Troubleshooting

• Connection failed: Run ssh <target> in Terminal, accept the host key if prompted, and verify the exact alias or destination.
• Authentication failed: Use a key available to your SSH agent or select Install SSH key in Remote SSH settings.
• CLI missing or incompatible: Run Test Connection, then Install / Update CLI.
• Agent command not found: Install and authenticate that provider’s CLI on the remote host, then verify its non-interactive PATH with ssh <target> 'command -v <provider-command>'.
• Agent reports ConnectionRefused: Test the provider endpoint from the host, for example with ssh <target> 'curl -I https://api.anthropic.com'. Any HTTP response confirms network access. If the connection fails, check remote DNS, proxy environment variables, and outbound firewall rules.
• Hooks or app commands fail: Confirm that the SSH server permits forwarding.
• No live updates or automatic naming: Check the managed CLI status and enable automatic updates.
• PR or MR actions unavailable: Confirm the repository has a supported remote and authenticate gh or glab on your Mac. A host-side forge CLI is optional.