Work on a repo on your home server over SSH

Updated November 15, 2026

Goal: the code and the agent are on your home server or a dev box, and you drive them from crystl on your Mac.

What you need

  • SSH access to the host, with your usual keys.
  • The agent installed on the remote machine. It runs there, not on your Mac.
  • Nothing to buy. SSH gems are free. CLI control commands and Guild features keep their usual tiers.

Steps

  1. Check the auto-tunnel is on. Open Settings (Cmd+,), go to remote → REMOTE SSH, and look at auto-tunnel for SSH sessions. It is on by default.

  2. Open the remote folder as a gem. Click the folder button at the bottom of the gem sidebar and switch from this mac to remote. Type the host in HOST (user@host, or a name from your ~/.ssh/config), or pick it from SAVED HOSTS. Type the repo’s folder in FOLDER and click open.

    Starting a new project there instead? Use the New Gem panel with the same remote switch. crystl creates the folder on the server, and runs git init there if you tick Initialize git repository.

  3. Log in if the host asks. A shard opens with crystl’s ssh to the host. Type your password or 2FA code there. crystl then cds the shard into the gem’s folder, and the gem’s sidebar row shows an ssh mark.

  4. Start your agent on the remote and work as usual. Approval cards appear on your Mac.

  5. Add shards with the + button. A new shard connects to the same host, reuses the connection with no second login, and lands in the gem’s folder.

  6. Go parallel on the remote by clicking new isolated shard in the shard bar’s creation column. The git worktree is created on the remote host under .crystl/worktrees/, and every merge or rebase runs there too. Nothing is copied to your Mac.

  7. If your model server is on that box, fill in base URL from the server on its open-model connection. A Tailscale address is right from your desk and wrong from the server, where the model server is just localhost.

What you’ll see when it works

Approval and question cards for the remote agent show up on your Mac exactly like local ones. Drag a file or paste an image into the SSH terminal and crystl SCPs it to /tmp on the remote and types the path. Click a remote file path and it downloads and opens in your local editor. Remote isolated shards get the branch icon and the same merge, keep, or discard prompt on close.

If panels don’t appear, check that the auto-tunnel is on, and that nothing else on the remote already holds port 19280 or /tmp/crystl-bridge.sock. An “address already in use” warning is harmless: the first tunnel is live and the hook script tries every path in order.

If the connection fails, the shard says so. Click reattach under the shard to try again.

Quit crystl and reopen it, and the shards reconnect and return to the folders they were in.

You can still type ssh user@myserver in any shard yourself. crystl wraps that call the same way, with the tunnels and the hooks. The gem keeps its local name and folder, though, so opening the remote folder as a gem is the better start.

Go deeper

  • remote SSH sessions for opening and creating remote gems, the wrapper internals, the file relay, and the full troubleshooting list.
  • isolated sessions for how remote worktrees are created and recovered.
  • Quest over SSH to run a whole party on the remote host.