---
title: "Remote workspaces"
description: "Whole workspaces hosted on another machine — files, repos, panes, and git all stay over there."
---
An SSH pane runs one shell on a remote machine. A **remote workspace** goes
further: tty7 runs a server on the far machine, and the whole workbench points
at it. Tabs, splits, the file tree, the git panel, the diff overlay, the process
list — all of it is the remote machine's, rendered here.
Nothing is synced or copied. The repository stays where it is.
## Connecting
⌘ ⇧ N, or the button at the bottom of the switcher
(⌘ ⇧ O). The form's host dropdown lists *This Computer*, every
saved SSH profile, your `~/.ssh/config` aliases and, on Windows, every WSL
distribution — type to filter when the list is long.
Or search for the machine by name in the switcher. One with nothing on it
yet appears under **Machines with no workspace yet**, and picking it opens
this form with that host already chosen.
tty7 connects over the same SSH stack as everything else, so profiles,
keychain credentials, and jump hosts all apply. A machine that is not
connected yet connects first, then creates the workspace in its home
directory.
The first connection asks:
> tty7 will write its server binary to *devbox* so this machine can host
> workspaces there. Nothing else on *devbox* is touched, and no sudo is
> used.
It shows the exact path, version, size, source, and SHA-256 before you
agree. Later upgrades on that machine install silently.
From then on the machine's workspaces sit in the switcher's flat list next
to your local ones, each row carrying the machine's name and link state,
and a new one opens like a local one.
## Knowing which machine you are on
A window on another machine says so, and keeps saying so. Under the workspace
name in the tab rail is a dot and the machine's name — green while the link is
up, amber while it is being made or remade, red once it has given up, with a
word beside it whenever the state is not the one you would assume:
```
[F] fable-marten ⌃⌄
● devbox · reconnecting
```
The tab rows below it stay quiet, because the badge above them already answered
the question. A row only names its own machine when that would *contradict* the
badge — an SSH pane opened inside a local workspace, or a `wsl` shell beside
Windows ones.
An empty remote workspace has no rail to carry the badge, so the home screen
names the machine a new tab would open a shell on.
## What gets installed
| | |
|---|---|
| **What** | A single self-contained `tty7-server` binary |
| **Where** | `~/.local/share/tty7/bin/tty7-server-cp` |
| **Privileges** | None. No sudo, nothing outside your home directory |
| **Hosts** | Linux (x86-64 or aarch64) and macOS (Apple Silicon or Intel) |
The Linux binary is linked fully static against musl, so it runs on any
distribution whatever its glibc vintage. The macOS one links only the libraries
every Mac already has. Either way nothing is installed beside it.
The binary is named after the wire dialect it speaks, so a client and a server
that disagree never quietly half-work — tty7 installs the matching one instead.
On Windows, a WSL distribution is handed the Linux server the installer already
shipped, so a WSL workspace needs no network access at all.
## Reattaching
Remote workspaces are the point at which persistence pays off twice: the panes
survive on the remote machine whether or not your laptop is awake, and you can
reattach from a different client entirely.
A strip along the top of the window says what the connection is doing —
*connecting*, *reconnecting (attempt 3)*, *disconnected*, or *taken over by
someone else*. Reconnection is automatic; a workspace another client has claimed
says so by name rather than fighting over it.
## Deleting a profile
Deleting an SSH profile forgets every local workspace entry that connected
through it. The confirmation names the profile's endpoint and counts the
entries going with it, and the profile's keychain credentials go too. Only the
bookmarks on this computer are touched — the sessions on the remote machine
keep running, and connecting to that machine again under a new profile brings
its workspaces back into the switcher from the machine's own list.
An entry holding a live or in-flight connection is left alone, and parks once
the link drops: it stops reconnecting on its own, keeps the name of the route
that made it rather than falling back to an internal id, and its switcher row
offers **Remove entry**. The sessions behind it are still on the machine,
waiting for a new profile.
## Keeping the server current
Two dialogs you may meet:
The machine is serving sessions from a build whose protocol this client
cannot speak. tty7 has already installed a matching server, but the one
already running is the one your sessions are on. **Update Server** replaces
it and **ends every session it is hosting** — including ones this window is
not showing. Cancel leaves the machine exactly as it is.
Same consequence, deliberately: every shell on that machine ends. Workspaces
and layouts are kept and come back with fresh shells.
Both of these end other people's work if the machine is shared. tty7 spells
out what will happen before either one runs — read it.
## What a remote pane cannot do
- **Fork an agent session.** The fork command would run against the *local*
agent, so tty7 does not offer it.
- **Move very large files through the Files panel.** Drag-and-drop across the
link is capped at what one control frame can carry; past that the panel tells
you to use [SFTP](/remote/sftp).
## From the CLI
```bash
tty7 machine ls # this machine plus every link the server holds
tty7 -m devbox ls # route any command to a linked machine
tty7 -m devbox run -- cargo test
```
`-m` matches the full link key (`me@devbox:22`) or just the host. It uses a link
the local server *already* holds — it will not dial a fresh connection, and it
says so rather than guessing. Connect from the switcher first.
[CLI overview →](/cli/overview)