Remote SSH Sessions

Updated November 16, 2026

Overview

A gem can live on another machine. Every shard in it connects to the host and lands in the gem’s folder there, isolated shards get their git worktree on the host, and leftover branches on the host can be reopened from your Mac.

Your agent runs on the host, and its approval cards and question cards still appear on your Mac and your phone. An automatic SSH wrapper makes that work: it sets up reverse tunnels back to the crystl bridge, installs the agent’s hooks on the host, and tracks the session for as long as it runs. How the wrapper works has the details.

You can open a remote gem from the app, from a crystl://ssh URL, or by typing ssh in a shard yourself.

Open or create a remote gem from the app

Two places in the app open a gem on another machine: the New Gem panel creates one, and the folder button opens a folder that is already there. Both need auto-tunnel on, which it is by default.

The remote machine does not need crystl. It needs an SSH login, and the agent you plan to run: the agent runs on the remote machine, so it must be installed and signed in there.

Before you start

  • You can log in. ssh <host> works from a terminal on your Mac. A password or 2FA prompt is fine, because you answer it in the shard.
  • The agent is ready on the host. Run claude, codex or your agent once there and sign in.
  • git is on the host, if you want crystl to run git init or make isolated shards.

Create a gem on the remote machine

  1. Open the New Gem panel.
  2. Switch the location from this mac to remote.
  3. Fill in HOST. The field takes user@host or an ssh config name. Under it, SAVED HOSTS lists hosts from your ~/.ssh/config, hosts of SSH gems you opened before, and Macs you have paired. Click one to fill the field.
  4. Fill in PATH, the parent folder on the remote machine. It starts at ~/. The gem’s folder is PATH plus NAME, the same as for a local gem.
  5. Choose the rest as you would for a local gem, then click create gem.

The panel closes and a shard opens with crystl’s own ssh to the host. If the host asks for a password, a passphrase, a 2FA code or a host-key answer, type it in that shard. Take as long as you need. Until you are logged in, the shard says:

crystl: setting up this gem once you're logged in to <host>.

After the login, crystl creates the folder on the remote machine and writes the files you picked in the panel: starter files, agent files, MCP config. If you ticked Initialize git repository, it also runs git init and makes the first commit there. Then it cds the shard into the gem’s folder.

If the folder already exists, crystl uses it and never overwrites a file that is already in it.

When a step fails, the shard prints one line and a card titled remote gem setup: <step> failed says what to try next. A failed folder create stops the steps after it. A failed file write does not stop the other files.

When setup is done, start your agent in the shard: type claude, codex or your agent’s command. Click + on the shard bar for another shard on the same host, or ⎇ for an isolated shard with its own worktree there.

Open a folder that is already on the remote machine

  1. Click the folder button at the bottom of the gem sidebar.
  2. Switch from this mac to remote.
  3. Fill in HOST, the same way as above.
  4. Fill in FOLDER, or leave empty for the home folder.
  5. Click open.

crystl creates nothing on the host. The gem is named <folder> · <host>, or after the host when FOLDER is empty.

Ports, keys and jump hosts

crystl runs ssh -- <host> with exactly what you typed in HOST, so the field takes no flags. If the host needs a port, a key file or a jump host, give it a Host entry in ~/.ssh/config and type that name. crystl stores no passwords and no keys.

If the connection fails

The shard says so and tells you what to do:

crystl: this gem couldn't connect to <host>. click reattach under the shard to try again. setup finishes once it connects.

Click reattach under the shard. It types crystl’s own ssh again, and the setup that was waiting runs after that login. An ssh you type by hand gives you a shell on the host. It does not run the waiting setup.

The ssh mark

A remote gem shows a small ssh mark on its sidebar row, between the icon and the name. The mark is dim until a shard in the gem has logged in, and dim again when none is connected.

With auto-tunnel off

With auto-tunnel off, the remote form says:

auto-tunnel is off, so crystl can't set up a remote gem. turn it on in settings → remote.

create gem is disabled for a remote gem. open still works and gives you an ordinary SSH shell, with no folder change and no setup.

A host that is one of your paired Macs

If the host you type is a Mac you have paired with this one, the form offers paired mac · open remote workspace. The remote workspace shows that Mac’s own gems, shards and history. An SSH gem gives you shells on it. You can still open the SSH gem.

From a window that drives another Mac

In a window that drives another Mac, create gem creates the gem on that Mac. this mac in the switch means the Mac you are driving, and remote connects by SSH from that Mac. The folder button follows the same rule.

Two things can stop it, and the panel says which:

  • you're connected to <host> read-only. turn on terminal control to create a gem there.
  • <host> runs an older crystl that can't create gems from here. update crystl on <host>, or run crystl open <path> in a shard on that Mac.

After a restart

Quit and reopen crystl and a remote gem comes back with its ssh mark. Each shard reconnects to the host and returns to the folder it was working in, so an agent session resumes from the right place. An isolated shard returns to its worktree. If the host asks you to log in again, answer in the shard.

What it costs

SSH gems are free. So is driving another Mac on your own network or through an SSH tunnel you set up yourself, and that stays true when the tunnel crosses the internet, as with Tailscale. Connecting through crystl’s relay needs Guild. This is the same rule the iPhone app follows. crystl CLI commands keep their own tiers.

Enable automatic tunneling in settings, remote, under REMOTE SSH:

  1. Open Settings (Cmd+,)
  2. Go to the remote page
  3. Toggle auto-tunnel for SSH sessions on

Once enabled, every ssh command you run in a crystl terminal is transparently wrapped by a shell function that sets up reverse tunnels and installs Claude Code hooks on the remote. Approval cards appear locally just like they do for local Claude sessions.

New terminal sessions pick up the setting immediately.

How the ssh() wrapper works

crystl injects a zsh ssh() function into every terminal via ZDOTDIR. When you type ssh user@host, the wrapper intercepts the call and runs command ssh with extra flags. Here’s what it does on every invocation:

1. Reverse tunnels

Two -R flags are added, one Unix socket and one TCP port, so the remote has multiple ways to reach the local bridge:

ssh \
    -R /tmp/crystl-bridge.sock:localhost:19280 \
    -R 19281:127.0.0.1:19280 \
    -o StreamLocalBindUnlink=yes \
    ...

The Unix socket is the primary path; the TCP forward is a fallback for hosts that don’t allow StreamLocalForward. The remote hook script tries them in order: configured address → Unix socket → SSH_CLIENT IP → TCP tunnel → localhost.

2. ControlMaster multiplexing

Every SSH session opens a ControlMaster socket at /tmp/crystl-ssh-$$-%C, kept alive for 30 seconds after the last client disconnects:

-o ControlMaster=auto
-o ControlPath=/tmp/crystl-ssh-$$-%C
-o ControlPersist=30

This lets crystl reuse the existing authenticated connection for SCP, file relay, and remote git operations without re-prompting for credentials.

3. Claude Code hook installation

Before the interactive shell starts, a Python one-liner runs on the remote that:

  • Writes ~/.claude/crystl-hook.sh, a bash script that POSTs hook payloads to the bridge (trying the configured address, Unix socket, SSH_CLIENT IP, TCP tunnel, and localhost in sequence, with a 2-second connect timeout)
  • Merges hook entries into ~/.claude/settings.json for PermissionRequest, PreToolUse, PostToolUse, Stop, StopFailure, UserPromptSubmit, SubagentStop, Notification, PermissionDenied, and SessionStart
  • Replaces its own earlier hook entries rather than stacking new ones beside them
  • Sets CRYSTL_GEM and CRYSTL_SHARD env vars so the remote can identify itself when posting to the bridge

Installation is idempotent: reconnecting to the same host doesn’t add duplicate entries.

4. OSC 7771 session tracking

The wrapper emits an OSC 7771 escape sequence before running command ssh:

\033]7771;ssh|user@host|/tmp/crystl-ssh-$$-%C\007

TerminalSession registers an OSC 7771 handler that stores the host and ControlMaster path on the session. This is how crystl knows a shard is remote, which ControlMaster to talk to for SCP operations, and which host to reconnect new shards to.

Your own shell, on the remote

A crystl shell on a remote host gives you everything a plain ssh host gives you. crystl points the remote shell at its own ZDOTDIR, and each of the four zsh startup files there — .zshenv, .zprofile, .zshrc, .zlogin — sources your own copy first and crystl’s part after. Your PATH, aliases, functions, and prompt all still work, and your files are never rewritten. A cd you put in your own config is honoured.

If crystl cannot set that up — every slot in use, or a state directory it does not own — it prints one line saying what is wrong and what to do about it, then starts your plain login shell with no crystl integration. A shell that works without the extras is better than no shell at all.

Configure hooks manually (optional)

If you prefer not to use the auto-tunnel, you can run the hook installer yourself. In settings, remote, under TROUBLESHOOTING, click “copy remote-install command” to copy a one-liner to your clipboard. SSH into your remote machine and paste it. It installs hooks to ~/.claude/settings.json with a fast-fail timeout.

You’ll also need to forward the bridge port:

ssh -R 19280:127.0.0.1:19280 user@remote-host

Or add it permanently to your ~/.ssh/config:

Host myserver
    HostName remote-host.example.com
    User myuser
    RemoteForward 19280 127.0.0.1:19280

Where remote shards start

Clicking “+” on the shard bar inside a remote gem creates a new shard on the same host. Where it lands depends on how the gem was opened.

A gem opened from the app or a crystl://ssh URL knows its host and its folder. The new shard connects to that host and lands in the gem’s folder, whatever folder the other shards are in. When a shard in the gem is already logged in, the new one reuses that connection with no second login. When none is, the new shard opens its own ssh and you log in there.

A local gem where you typed ssh yourself has no stored folder. There the new shard follows the current one:

  • SSH session: the new shard runs ssh user@host automatically, reusing the ControlMaster connection (no re-auth)
  • Working directory: after the SSH handshake, it cds into the same remote path the current shard is sitting in

In that second case, crystl figures out the remote cwd by reading the prompt from the terminal buffer. It scans up to 3 rows above the cursor looking for a line that contains the SSH hostname and matches the pattern user@host:path# (or $ or %). The hostname match is important: it prevents local prompts (from tmux, screen, or nested shells) from being mistaken for remote ones.

// Simplified — see TerminalWindow+Sessions.swift:parseRemoteCwdFromPrompt
for row in stride(from: cursorRow, through: max(0, cursorRow - 3), by: -1) {
    let line = terminal.getLine(row: row).translateToString()
    guard line.contains(hostname) else { continue }
    // match "user@host:path#"
    // ...
}

If the cwd can’t be parsed (unusual prompt format, or the prompt has scrolled off), the new shard lands in the remote home directory. A gem opened from the app does not depend on the prompt at all.

Remote git worktrees

Clicking new isolated shard in the shard bar’s creation column (hover the +) in a remote gem creates a git worktree on the remote host, not locally. The new shard SSHs to the same host and cds into the worktree path.

This is the remote mirror of local isolated shards: multiple agents can work on the same remote project in parallel without stepping on each other’s files.

You do not pick the name. crystl asks the host which crystals it already holds and counts up from the name it was given until one is free, so the button works on a remote gem without a naming step and a new shard never lands on a branch an old one left behind. A name you type yourself still means that exact shard, and so does reattaching one. See leftover branches and fresh names.

An isolated shard needs a logged-in connection to the host. If none is open yet, you still get a shard, and it says:

crystl: no connection to <host> is open yet, so this shard opens in the gem's main folder, not its own worktree. once it's logged in, click ⎇ to make an isolated one.

When a remote create cannot go ahead, the reason is written into a shard you can still read, and you keep a working shell in it. A host that stops answering is bounded rather than waited on forever: crystl gives up after 30 seconds and leaves you that same shell and reason.

From the CLI, crystl shard create --isolated waits up to 45 seconds for a remote isolated shard, so a slow login does not read as a failure. See shard create.

Remote: ~/myapp (main branch)
├── diamond     — the gem's main folder (~/myapp)
├── ⎇ aquamarine — ~/myapp/.crystl/worktrees/aquamarine (branch: crystl/aquamarine)
└── ⎇ sapphire  — ~/myapp/.crystl/worktrees/sapphire   (branch: crystl/sapphire)

Lifecycle

RemoteGitWorktree mirrors the local GitWorktree API but executes every git command over SSH via the shared RemoteSession (same ControlMaster connection as the parent shard). All operations happen remotely:

Operation Runs on remote
Create git worktree add -b crystl/{name} .crystl/worktrees/{name}
Symlink configs CLAUDE.md, AGENTS.md, .mcp.json, .claude/ into the worktree
Merge git merge crystl/{name} into the parent branch
Rebase git rebase main inside the worktree
Close git worktree remove and optionally git branch -D

No local state is created; everything is on the remote under .crystl/worktrees/. The merge and rebase actions on the shard tab run over the same SSH connection.

Close prompts

Closing a remote isolated shard with commits shows the same prompt as local worktrees: merge to main / keep branch / discard. The selected action is executed remotely. Closing a gem with multiple unmerged remote branches shows keep branches / discard all / cancel.

Reuse and recovery

If you reconnect a shard whose worktree directory still exists and is functional, crystl reuses it as-is (preserves any uncommitted changes). If only the branch exists (the directory was cleaned up), the worktree is recreated from the branch. Broken worktree dirs are removed and rebuilt.

Reattach after a dropped connection

When the connection to a host drops (the Mac slept, the network changed), the band under that shard’s terminal says connection to dropped and offers reattach. One click types the reattach command into the shard, and you are back in the same remote session with the agent where you left it.

The click is careful about where it types. It only types into an idle shell with a clean line. If a program is running in the shard, if there is unsent text on the line, or if crystl is about to start an agent there, the band says why and types nothing. Click again when the shard is back at the prompt. A click that lands just after you pressed Enter waits a moment for that command to start before it decides.

From the remote workspace on another Mac, the same button asks the host to do the reattach. The notice stays until the host’s roster confirms the shard is connected again, and says so if it cannot confirm.

Remote orphaned branches

The branches button in the shard bar lists orphaned crystl/* branches: worktree branches from previous sessions that still have commits or uncommitted changes. It appears only when such branches exist. For remote gems, the list includes orphans on the remote host.

Clicking a remote orphan reopens it: a new shard is created, SSHs to the host, and RemoteGitWorktree.create() either reuses the existing worktree directory or rebuilds it from the branch. Uncommitted changes are preserved.

Remote orphans are queried asynchronously (RemoteGitWorktree.orphanedBranches() runs on a background queue) so the branches list opens instantly even when the SSH round-trip is slow. The list populates in place once the query returns.

crystl quest parties over SSH

crystl quest parties work fully over SSH. When you start a quest from a remote shard, all four mode combinations are supported: open and sealed, local and remote. The quest setup panel detects the SSH session, switches the directory picker to the remote filesystem, and creates agent shards that inherit the SSH connection. In sealed mode, worktrees are created on the remote host using RemoteGitWorktree. Approval cards and chat messages relay through the same tunnel described above.

See Starting a quest > crystl quest over SSH for the full walkthrough.

file relay

When a session is connected via SSH with auto-tunnel enabled, crystl bridges local resources to the remote:

Drag & drop / image paste

Drag a file or paste an image into an SSH terminal and crystl SCPs it to /tmp on the remote and types the remote path. No manual file transfer needed. Uses the SSH ControlMaster socket opened by the ssh() wrapper, so there’s no extra auth prompt.

Click-to-open remote files

Click a file path in an SSH session and crystl downloads it via SCP (through the same ControlMaster) to a local temp directory, then opens it in your default editor.

Local model servers over SSH

A shard on a remote host gets each enabled open-model connection’s base URL from the server when you set one, and falls back to the base URL when you don’t. That’s how a home GPU box you reach at a Tailscale address from your Mac still resolves to localhost for an agent running on the box itself.

Gem settings over SSH

When configuring a gem that’s running in an SSH session, CLAUDE.md templates, agent files, and .mcp.json configs are written directly to the remote filesystem.

How it works (end-to-end)

Claude Code hooks POST to the bridge whenever a tool needs permission. On a remote machine, the hook script tries several paths in order until one succeeds:

Remote: Claude Code --> ~/.claude/crystl-hook.sh
                              |
                              v
                   1. configured bridge address
                   2. Unix socket via -R /tmp/crystl-bridge.sock
                   3. SSH_CLIENT IP on port 19280
                   4. TCP forward via -R 19281:127.0.0.1:19280
                   5. localhost:19280 fallback
                              |
                         SSH tunnel
                              |
Local:  Crystl BridgeServer  <-- shows approval card

Every hop carries the auth token (Authorization: Bearer ...) and gem/shard headers (X-Crystl-Gem, X-Crystl-Shard) so the bridge can route the decision back to the right panel.

Troubleshooting

Approval cards don’t appear over SSH:

  • Make sure the auto-tunnel is enabled in settings, remote
  • Check that nothing else on the remote is bound to port 19280 or to /tmp/crystl-bridge.sock
  • If connecting to the same host from multiple crystl shards, only the first tunnel binds the port; the others fall through to the Unix socket or SSH_CLIENT IP path

“Address already in use” warning:

  • Another SSH session may already be forwarding port 19280 or the Unix socket to this remote host
  • Harmless: the first tunnel is still active, and the remote hook script tries all paths

Claude Code hooks not firing on remote:

  • Normally the auto-tunnel installs hooks automatically on every connect
  • If you connected without the wrapper, use the “copy remote-install command” button in settings, remote, and run it manually on the remote
  • Check that ~/.claude/crystl-hook.sh exists and is executable (ls -la ~/.claude/)

New shard on remote gem doesn’t land in the right directory:

  • This applies to a local gem where you typed ssh yourself. A gem opened from the app or a crystl://ssh URL always lands new shards in the gem’s folder
  • The prompt parser needs the SSH hostname to appear in the prompt line; unusual prompt formats (e.g. pure path, no user@host) aren’t detected
  • Fix: include the hostname in your remote PS1, or manually cd after the new shard connects

Remote worktree operations hang:

  • ControlMaster connections have a 30-second persistence window; if the original shard exited long ago, the shared socket may be gone
  • The operation will re-authenticate, which may prompt for keys; this is expected