tty7/docs/remote/workspaces.mdx

---
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.

<Frame caption="Placeholder — screenshot: a remote workspace open, sidebar showing remote repos, with the machine name in the strip">
  <img src="/images/placeholder.svg" alt="A remote workspace in tty7" />
</Frame>

## Connecting

<Steps>
  <Step title="Open the New Workspace form">
    <kbd>⌘ ⇧ N</kbd>, or the button at the bottom of the switcher
    (<kbd>⌘ ⇧ O</kbd>). 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.
  </Step>
  <Step title="Pick a machine">
    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.
  </Step>
  <Step title="Approve the server install, once">
    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.
  </Step>
  <Step title="Open a workspace">
    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.
  </Step>
</Steps>

## 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-c<control>p<protocol>` |
| **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:

<AccordionGroup>
  <Accordion title="Update tty7's server on “devbox”?">
    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.
  </Accordion>
  <Accordion title="Restart tty7's server on “devbox”?">
    Same consequence, deliberately: every shell on that machine ends. Workspaces
    and layouts are kept and come back with fresh shells.
  </Accordion>
</AccordionGroup>

<Warning>
  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.
</Warning>

## 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)