Tether — Lightweight SSH Sync

Edit locally. Run remotely. Install nothing on your server. Two-way sync over SSH so every extension runs on your machine and the server only ever sees a normal login.

Tether lets you work on a remote machine without turning it into your development environment. It is free, open source, and made for servers where a full remote IDE is too much: small boards, old distributions, shared login nodes, locked-down hosts, and slow links.

With Tether you can:

• Develop against a remote folder with the language servers, linters, formatters, Git tools, and AI assistants you already use — all running locally.
• Keep the server clean. Tether installs nothing on it: no VS Code Server, no agent, no daemon.
• Build, run, and test in a terminal that executes on the server, and watch the output files appear in your workspace.
• Keep working when the connection drops. Offline edits are sent when it returns.
• Use the editor you prefer: VS Code, VSCodium, Cursor, Windsurf, and other editors built on VS Code.

Getting Started

Install from the Visual Studio Marketplace or Open VSX, or open Quick Open (Ctrl+P / Cmd+P) and run:

ext install filippobrogi00.tether-sync

Then:

1. Click Tether in the status bar (bottom left), or run Tether: Connect Folder… from the Command Palette (F1).
2. Choose a server. Hosts from your ~/.ssh/config are listed. You can also type user@hostname.
3. Choose a folder on the server by clicking through its directories — or, if you already have a local project open, pair that folder with one on the server.

Connecting starts continuous two-way sync. There is no configuration file to write.

Why Tether

Remote - SSH moves your editor's backend onto the server. Tether leaves the editor where it is and moves only your files.

Tether is worth trying if you have run into any of these:

• GLIBC_2.28 not found, or a warning that the host does not meet the prerequisites, on CentOS 7, RHEL 7, Ubuntu 18.04, or an old embedded image.
• ~/.vscode-server eating your home directory quota on a shared machine.
• VS Code Server processes using CPU and memory on a login node or a small board.
• No Remote - SSH in your editor's extension gallery.
• Sessions that freeze or reload on a slow or unstable link.

If you need the editor to be on the server — for remote debugging or a repository too large to copy — Remote - SSH is the right tool. The two work well side by side.

Features

Stay in Sync — Two-Way File Sync

• Push on every change. Local changes are sent the moment a file changes, not only when you save, so git checkout, formatters, and scripts are covered too.
• Pull when it matters. Changes made on the server are picked up after each terminal command, when you return to the window, and once a minute.
• Fast first connect. Large one-sided trees are transferred as one compressed tar archive when tar is available, then fall back to per-file SFTP.
• Compressed incremental transfers. Larger file changes are gzip'd on the wire when the server has gzip (optional host rsync when present on both sides).
• Skip what you do not need. .git/, node_modules/, virtual environments, and caches are ignored out of the box. Add your own patterns in .gitignore syntax, in settings or in a .tetherignore / .connectignore file.
• Pair two folders that already have files. Identical files are matched by a SHA-256 hash computed on the server, so nothing is copied twice.

Never Lose Work — Conflicts and Safety Nets

• Conflicts are never overwritten. When a file changed on both sides, Tether stops and shows the two versions side by side. Keep yours, the server's, or both.
• Deletions are deliberate. A deletion is mirrored only for files that were in sync before. Files removed locally because they were deleted on the server go to your system trash.
• Mass deletions ask first. Removing more than 25 files in one sync needs your confirmation, and so does a side that suddenly looks empty. A folder that has gone missing (for example an unmounted disk) stops the sync instead of deleting everything.
• Uploads are atomic. Each file is written under a temporary name and renamed into place, so the server never sees half a file.
• A changed host key refuses the connection.

Run Where the Code Lives — Server Terminal, Remote View, and Port Forwarding

• Remote Terminal gives you a shell on the server, already inside the remote folder, kept alive with tmux or screen when available. Disconnect / close asks Terminate or Keep alive.
• Remote View adds a native second Explorer root (tether:) for drag-and-drop between local and remote.
• Port forwarding makes a web app or service running on the server available at http://localhost:<port>.
• Results come back by themselves. Logs, build output, and generated files are pulled into your workspace shortly after the command that created them.

Sign In the Way You Already Do — SSH Config, Keys, and 2FA

• Your SSH config is the configuration. Hosts, users, ports, identity files, Include files, and ProxyJump chains are read from ~/.ssh/config.
• Every common sign-in works: SSH keys, ssh-agent, key passphrases, passwords, and one-time codes (keyboard-interactive).
• Host keys are verified against your known_hosts. A first connection shows the fingerprint, and a changed key refuses to connect.

Know Where You Stand — One Status Bar Item

Click the item for Sync Now, port forwarding, conflict review, the log, and everything else.

Under the Hood

For every file, Tether records what both sides looked like the last time they agreed. On each sync it compares each side against that record, never the two sides against each other. Clock differences between machines therefore do not matter, and "deleted here" is never mistaken for "created there". Unison and Mutagen work the same way.

The server is listed with one find command when available (hundreds of thousands of files in one round trip) and over SFTP otherwise. First-time pairing of two non-empty folders compares SHA-256 hashes computed on the server, so identical files are never transferred. Cold one-sided syncs with many files use a single tar+gzip archive when possible.

"Asks you" follows tether.conflictPolicy, so you can also let one side always win.

Commands

All commands are in the Command Palette under Tether. Sync Now, port forwarding, conflict review, and the log also live in the status-bar menu.

Reconnect behavior

• Connection dropped while working: status goes offline and Tether retries with backoff; local edits keep and sync when the link returns.
• Quit VS Code (or reload the window): you are asked whether to Terminate or Keep alive remote terminals (tmux/screen). Sync stops and the SSH session is closed. The folder pairing is kept with “resume on open”, so the next time you open that workspace it connects and syncs again automatically.
• Disconnect: same terminal prompt, then stops sync and turns off resume for that folder. Use Reconnect to Last Used Server (or Connect Folder…) when you want it again.

Settings

Tether works without any configuration. These settings are for fine-tuning.

Ignored by default: .git/, node_modules/, __pycache__/, .venv/, venv/, .mypy_cache/, .pytest_cache/, *.pyc, .DS_Store, Thumbs.db.

.git/ is ignored on purpose. Use Git on your computer, where your Git extensions are.

Requirements

Your computer

• VS Code 1.85 or later, or an editor built on it.
• Windows, macOS, or Linux.
• Nothing else. Tether speaks SSH and SFTP itself, so it needs no ssh, scp, or rsync on your machine.

Your server

• Any Linux or Unix host running an SSH server with SFTP enabled (the OpenSSH default).
• No root access, no installation, and no extra open ports.
• No kernel, glibc, or CPU architecture requirement — old distributions and small ARM boards are fine.

Note: Windows servers are not supported.

Security

Tether copies files from the server onto your computer. Sync only with servers you trust, and keep Workspace Trust turned on: a hostile server could plant files (tasks, workspace settings) that tools on your machine would act on.

• Host keys are checked on every connection. Tether never edits your SSH files. Keys you accept are remembered in its own storage.
• Passwords are saved only if you choose Remember, and then only in your system keychain. Key passphrases are remembered for the current session only.
• Your SSH config is read, never executed. Match exec rules are not run.

See SECURITY.md to report a vulnerability.

Known Limitations

Tether trades one thing for its light footprint: your extensions see local files, not the server's environment.

• Code intelligence for dependencies that exist only on the server (a Python environment, system headers) is incomplete unless you install them locally too.
• Run, build, test, and debug happen in the server terminal, not through the Run and Debug view.
• Symbolic links and empty folders are not synced.
• Files are transferred whole, without rsync-style deltas, so very large files that change often are a poor fit. Files over 100 MB are skipped by default.
• Permissions belong to the server. Set them there with chmod and they are kept on every upload.
• ProxyCommand in your SSH config is not supported yet. ProxyJump is.

Troubleshooting

Run Tether: Show Log first (or open it from the status-bar menu). It records every connection attempt and every file Tether touched.

Roadmap

• Delta transfers for large files.
• Symbolic links and empty folders.
• ProxyCommand support.

Release Notes

See the changelog.

Contributing

Development setup, tests, and pull-request guidelines are in CONTRIBUTING.md.

npm install
npm run build
npm test
# Press F5 in VS Code / Cursor to launch an Extension Development Host

src/core/ has no dependency on VS Code and can be reused as a library or CLI.

• Search existing issues or open a new one for bugs and feature requests.
• Ask questions and share setups in Discussions.

Telemetry

Tether collects no telemetry and makes no network connections other than to the servers you choose.

License

MIT

Tether is an independent open-source project. It is not affiliated with or endorsed by Microsoft.