Switch Between Hosts
Move a Daintree window between this machine and your hosts: the host chip and its states, the host menu, which project a switch opens, new windows, Other hosts in the project switcher, shortcuts, disconnecting and restored windows.
The Host Chip
The host chip sits in the toolbar just right of the project name. It appears once you have added at least one host, so on a single machine you never see it, and it never appears on Windows.
- A window on this machine shows a small quiet chip with an Apple or Linux mark and This Mac, or This machine on Linux.
- A window on a host shows a larger bordered pill, like the project pill beside it, with a server icon and SSH · studio-01. Its tooltip says what that means: Working on studio-01 over SSH. Project files, terminals and agents run there.
The window title says it too: a remote window is titled Atlas Ledger — studio-01. In the chip, long host names are shortened in the middle so their last characters always show.
When something is wrong, a word follows the name:
| Chip word | Meaning |
|---|---|
| no reply | Connected, but nothing has come back for several seconds. It clears when traffic resumes; a longer silence turns into a reconnect. |
| connecting… | The link is being set up or re-established. |
| unreachable | The last attempt failed. Daintree keeps retrying with backoff. |
| can't connect | The two machines speak different link protocols. One of them needs an update, and the host menu offers it for the side that is behind. |
| not connected | You disconnected this window from the host. |
| viewing | Another machine has control of this project, so this window shows it read-only. See Who Has Control. |
A host on a different but compatible build adds no word to the chip. It shows a one-time warning instead; see Different Builds.
The Host Menu
Click the chip, or press Option-Shift-Command-H Unavailable on this platform Control-Alt-Shift-H (macOS and Linux only), for the host menu. Under Working on it lists this machine first and then every host alphabetically, with a check beside the one this window is on and a short state on the right:
| State | Meaning |
|---|---|
| Local | This machine. |
| Connected | The link is up. Who has control of a project shows in that project's window, and in the Hosts overview's Driving row. |
| No reply | Connected but silent, with Last heard … beneath. |
| Connecting… | The link is being set up or re-established. |
| Not connected | Not connected yet, or disconnected from this device. |
| Host mode off | ssh reached the machine, but Daintree isn't serving there. |
| Unreachable | With Last seen … beneath when it has been seen before. |
| Can't connect | With Needs a compatible build beneath. |
Below the list:
- Open in new window ›: every machine, to open in a new window instead of this one.
- Continue this branch on… ›: every other host. Shown when a project is open. It brings the project and its branch across; see Continue a Branch on Another Host.
- Update studio-01 or Update this machine: only when a host refused the connection for its build.
- Hosts overview…, Add host… and Manage hosts… (Settings → Hosts).
- Disconnect studio-01 from this device: in a window on a host, while its link is connected or connecting.
The menu deliberately carries no load figures. CPU, memory pressure, agent counts and projects for every machine are in the Hosts overview.
What a Switch Does
Click a host in the menu and this window goes to it, as it is. Nothing is fetched, pushed, cloned or created, and it makes no difference whether a project is open. The window opens, in this order:
- the project this window last had open on that host;
- otherwise the project this machine last had active there, which the host remembers for each machine that connects to it (for up to 64 machines, until the host restarts);
- otherwise nothing moves yet: the window stays where it is and shows a list of the host's projects, and picking one completes the switch.
Switching back to This Mac opens this window's most recent local project that no other window has open, otherwise the most recently opened local project that isn't closed or open in another window, otherwise a project picker.
- One window per project. If another window already shows that project on that host, that window comes to the front instead, and this one stays where it was.
- The latest click wins. Clicking another host while the first is still connecting cancels the first.
- Waiting. A switch waits up to 20 seconds for the host to answer, and longer (up to two minutes) while Daintree is being started there. A set-up host whose Daintree has stopped is started automatically, the way it was set up; you see only Connecting….
Getting Back to This Machine
- Click the chip and choose This Mac.
- Open a local folder (Open Recent, or Open project): a window on a host comes back to this machine to open it.
- Switch to last workspace toggles back to where you were.
The Projects Picker
When there is no project to return to, the window shows a searchable list headed Projects on studio-01, with each project's name and its path on the host. Enter or a click opens it in this window; Cmd-click (Ctrl-click on Linux) opens it in a new one. A host with no projects yet says so and offers Open studio-01 in a new window.
Open a Host in a New Window
Cmd-click a host in the menu (Ctrl-click on Linux), or use Open in new window ›, to leave this window where it is and open the host in another. The new window opens the project this machine last had active on that host if the host remembers one, and otherwise the host's project list. Windows on different hosts sit side by side like any other windows.
Other Hosts in the Project Switcher
The project switcher lists the projects of the host this window is on, and then an Other hosts section: the projects on every other connected host (and on this machine, from a remote window), grouped under each host's name, with their paths. Hosts that aren't connected are left out. Your search filters these rows too.
Choose one and the window moves to that host and opens that project directly. Cmd+Enter or Cmd-click (Ctrl on Linux) opens it in a new window.
Right-click a project row for Open on… ›: a submenu of the other hosts, each marked with whether it has the project. A check means the host has a project with the same remote; clone means it doesn't; not connected grays the host out. Choosing one opens the dialog that brings the project across; see Continue a Branch on Another Host.
Keyboard and Command Palette
| Command | What it does |
|---|---|
| Switch host… Option-Shift-Command-H Unavailable on this platform Control-Alt-Shift-H | Opens the host menu. With no hosts yet, opens Settings → Hosts. |
| Hosts overview… | Opens the Hosts overview. |
| Add host… | Opens Settings → Hosts and the Add host dialog. Always listed. |
| Forward port… | Opens the Ports view. |
| Switch to last workspace Option-Command-= Control-Alt-= Control-Alt-= | Toggles to the previous workspace, a project or a scratch, even when the project is on another host. |
Switch host…, Hosts overview… and Forward port… appear in the command palette once a host exists; Add host… and Switch to last workspace are always there. The Switch host… shortcut is not registered on Windows.
Disconnecting and Restarting
Disconnect From a Host
In a window on a host, Disconnect studio-01 from this device closes this machine's connection to it. Remote work on the host isn't stopped: its terminals and agents carry on. The window shows Disconnected from studio-01 with a Connect button, and its terminals are read-only until you connect again. If ports are forwarded from that host, Daintree asks first, because those forwards stop working here until the host is connected again.
After Daintree Restarts
Windows that were on a host come back on that host. Each opens on this machine first and then switches to its host's project once Daintree is ready. If the host can't be reached, the window stays on this machine with Couldn't reopen this window on studio-01 and a Retry button. Its place on the host is kept for the next launch until you open something else in it.
When a Switch Fails
A failed switch leaves the window where it was and shows Couldn't switch to studio-01 with one way forward:
| Message | Action |
|---|---|
| Couldn't reach this host. Check that it is on and try again. | Retry |
| Daintree isn't running in Host mode on studio-01. Set it up to work there. | Set up… opens the host's setup in Settings → Hosts. |
| This host runs a different Daintree build. Update it to connect. | Update studio-01 or Update this machine |
More symptoms and fixes are in Troubleshooting Remote Hosts.