# Work on a repo on your home server over SSH

> Run agents on a remote machine while approval panels, file drops, and worktrees still behave like they're local.

**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:

   ```bash
   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](/docs/open-models/#remote-vantage-when-the-agent-is-somewhere-else). 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

- [remote SSH sessions](/docs/remote-ssh/) for the wrapper internals, the file relay, and the full troubleshooting list.
- [isolated sessions](/docs/isolated-sessions/#remote-isolated-shards) for how remote worktrees are created and recovered.
- [Quest over SSH](/docs/starting-a-quest/#crystl-quest-over-ssh) to run a whole party on the remote host.

---
Source: https://crystl.dev/docs/scenario-work-over-ssh/