Connect an editor over SSH
To work on a Greenhouse session in VS Code, Cursor, Zed, or a terminal, connect to the machine over SSH. The connection goes through the Orchard server, so the machine does not need to accept connections from the internet, and you keep the tools and settings of your own editor.
Your SSH client runs orchard sandbox proxy as its ProxyCommand. That command carries the connection over an authenticated WebSocket to the Orchard server, and from there to the machine.
Prerequisites
Section titled “Prerequisites”- Host access to the machine. The server refuses this connection for guests, because the machine holds the host’s credentials. Superadmins can also connect.
- A running machine.
- The Orchard CLI, installed and signed in.
- If the CLI authenticates with an API token, the
execscope on that token. To create one, runorchard auth token create --scope exec.
1. Configure SSH
Section titled “1. Configure SSH”Run the following command on each computer that you connect from:
orchard sandbox ssh-config --installThe command makes these changes. You can run it more than once.
-
It generates a key at
~/.orchard/ssh/id_ed25519, unless one exists. -
It registers the public key as an SSH identity on your account. Every machine you host trusts all of your identities.
-
It writes
~/.orchard/ssh/configwith one block for all of your machines:Host orchard-*User devIdentityFile ~/.orchard/ssh/id_ed25519IdentitiesOnly yesProxyCommand "/path/to/orchard" sandbox proxy --host '%n'StrictHostKeyChecking accept-newUserKnownHostsFile ~/.orchard/ssh/known_hostsServerAliveInterval 30 -
It adds
Include ~/.orchard/ssh/configto~/.ssh/config.
2. Connect
Section titled “2. Connect”To open the current session in an editor:
- In the workspace title bar, select the editor button. It shows the editor you used last.
- To choose another editor, open the menu next to the button.
- Select VS Code, Cursor, or Zed. The Terminal item gives you the
sshcommand to copy.
The editor opens the session’s worktree, for example /persist/home/.worktrees/app/fix-login-a1b2c3. VS Code requires the Remote - SSH extension.
| Editor | Link |
|---|---|
| VS Code | vscode://vscode-remote/ssh-remote+orchard-<name>/<worktree> |
| Cursor | cursor://vscode-remote/ssh-remote+orchard-<name>/<worktree> |
| Zed | zed://ssh/orchard-<name>/<worktree> |
To connect from a terminal, use the machine’s name:
ssh orchard-my-machinescp ./notes.md orchard-my-machine:~/The connection is ordinary SSH. Port forwarding, agent forwarding, rsync, and scp work.
Connect without changing your SSH config
Section titled “Connect without changing your SSH config”orchard sandbox ssh opens a shell without the setup above. Add --start to start a stopped machine first. Arguments after -- go to ssh.
orchard sandbox ssh my-machine --startorchard sandbox ssh my-machine -- -L 3000:localhost:3000To print a Host block for a machine and paste it into a config by hand, run orchard sandbox ssh-config my-machine.
Host keys
Section titled “Host keys”Each machine generates SSH host keys on first boot and stores them in /persist/hostkeys. A stop or start does not change them.
When the proxy connects, the CLI fetches the machine’s current host keys from Orchard and updates ~/.orchard/ssh/known_hosts. This covers a machine that you deleted and recreated under the same name. The CLI does not change ~/.ssh/known_hosts.
You can now open any session you host in your editor. To prepare each new worktree with dependencies, configure a setup script.
Related resources
Section titled “Related resources”- Troubleshooting Greenhouse - Fix a changed host key or a refused public key.