Work on a repo on your home server over SSH

Updated August 10, 2026

Goal: the code and the agent live 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 for the SSH wrapper itself. CLI control commands and Guild features keep their usual tiers.

Steps

  1. Turn on the auto-tunnel. Open Settings (Cmd+,), go to remote → REMOTE SSH, and toggle Auto-tunnel for SSH sessions on. New terminal sessions pick it up immediately.

  2. SSH the normal way, from a shard in the gem:

    ssh user@myserver

    crystl wraps the call: it adds reverse tunnels back to the local bridge, opens a shared ControlMaster connection, and installs the Claude Code hooks on the remote. Reconnecting to the same host doesn’t duplicate anything.

  3. Start your agent on the remote and work as usual. Approval panels appear on your Mac.

  4. Add shards with the + button. A new shard in a remote gem SSHes to the same host automatically, reusing the connection with no re-auth, and lands in the same remote directory you were working in.

  5. Go parallel on the remote by clicking the worktree row 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.

  6. If your model server is on that box, fill in as seen from remote 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 panels 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 a new shard lands in the home directory instead of where you were, the prompt parser couldn’t find the hostname. crystl reads the remote working directory out of the prompt line, so include the hostname in your remote PS1, or just cd after connecting.

Go deeper