Remote workspaces keep SSH destinations and layout metadata even when the live connection drops.
This guide covers reconnect flow, what is preserved, and how it differs from a pure blank local terminal.
Prerequisites
- A remote workspace previously connected
- Valid SSH credentials or agent
Steps
- 01
Confirm it is remote, not a blank local portal
If the tab is a remote host and the status strip shows disconnect/warning, use remote reconnect—not only Doctor blank-terminal recovery. For pure black local panes see Fix a Blank Terminal Screen.
- 02
Use the reconnect affordance
From the remote summary or Remote explorer, reconnect with the saved destination. Secrets may need re-entry depending on how the session was preserved.
- 03
Reattach PTY / open a fresh remote terminal
After SSH is up, focus a terminal pane. If the surface is stale, open a new remote terminal in the same workspace so cwd and remote tools return.
- 04
Re-run long agents carefully
Do not assume the old remote agent process still exists after a hard network drop. Check with
ps/job control before starting a second Claude Code or deploy.
FAQ
Are remote files deleted on disconnect?
No. Disconnect affects the session, not the remote disk. Local workspace layout is restored from session snapshots when possible.
Password every time?
Depends on keychain/agent and whether relay secrets were wiped for safety. Prefer SSH keys + agent for daily use.