Add a Remote Host
Add a Mac or Linux machine as a Daintree host: SSH prerequisites, the Find, Check, Install, Enable and Advise steps, SSH targets and discovery, and managing, updating and removing hosts.
Before You Start
Daintree connects to a host with the system ssh, non-interactively. If ssh can reach the machine with a key and no prompt, Daintree can reach it the same way, through one of the target forms below. Check that first, from the machine you will work on:
ssh you@studio-01.local 'echo ok'If that prints ok without asking for anything, you are ready. If it asks for a password, a passphrase or to confirm a host key, sort that out in a terminal first:
- No key on the host yet:
ssh-copy-id you@studio-01.localcopies your public key into the host's~/.ssh/authorized_keys. - A passphrase on your key: add it to your ssh agent (
ssh-add, or your Keychain, 1Password or another agent) sosshnever has to ask. - A new host key: connect once by hand and accept it, so it lands in
~/.ssh/known_hosts. - A Mac host: turn on Remote Login in System Settings → General → Sharing. See Set Up a Mac as a Host.
- A Linux host: install and start
openssh-server. See Set Up a Linux Host.
Your ~/.ssh/config applies: HostName, User, Port, IdentityFile, ProxyJump and the rest. Daintree adds its own connection-sharing options, turns agent and X11 forwarding off, and leaves out port forwards your config sets up, adding only its own. A host on a non-standard port or behind a jump host works through a config alias.
Open the Add Host Dialog
Open Settings → Hosts (in the Integrations group) and click Add host. The same dialog opens from Add host… in the command palette, which is always listed, and from Add host… in the host menu once you have one host.
The dialog walks five steps, shown across the top: Find, Check, Install, Enable and Advise. Steps that have nothing to do are skipped: a host that already runs your build goes straight from Check to Enable.
1. Find
Under Machines found, Daintree lists machines it can see without asking you anything:
- Tailnet: online macOS and Linux peers from
tailscale status, when Tailscale is installed. The target is the peer's MagicDNS name, or its Tailscale IP address when it has none. - Local network: Bonjour adverts on your network. That covers machines already running Daintree in Host mode, Macs with Remote Login turned on, and Linux machines that publish ssh through Avahi. Daintree's own adverts carry the platform; a plain ssh advert shows Platform not seen yet.
- Added: a machine already in your host list. It stays listed but can't be picked again.
Local-network adverts for a port other than 22 are left out, and so is this machine. Discovery shows only that a machine answered; whether Daintree is ready there is what the next step checks. Click a row to fill in its SSH target and name.
Or fill in the fields yourself:
- SSH target:
user@host, a host name, an IP address, or an~/.ssh/configalias. - Name: how the host appears in Daintree: in the chip, the menu, panel titles and banners. Left blank, it defaults to the first part of the target, so
you@studio-01.localbecomesstudio-01. You can rename it later; the host's own name never changes.
| You enter | Means |
|---|---|
you@studio-01.local | A machine on your local network, by its Bonjour name |
you@devbox.tail1234.ts.net | A Tailscale MagicDNS name |
devbox | An alias from ~/.ssh/config, with its port, user, key and jump host |
you@192.168.1.20 | An IP address |
:port suffix or an IPv6 address. Put either in an ~/.ssh/config alias and enter the alias. Discovered machines usually carry no user name, so ssh uses your User setting or your local user name; edit the target to you@studio-01.local if the accounts differ.2. Check
Check host connects over ssh and reports what it finds, line by line:
| Line | What it says |
|---|---|
| SSH | Works, or Didn't connect with ssh's own last lines of error underneath |
| Platform | For example macOS · Apple silicon or Linux · x64 |
| Installed | Daintree isn't installed, or the version and commit found there |
| Matches this machine | Same build, Different build or Can't tell |
| Host mode | Listening, or Off |
What you can do next depends on the result:
- Same build: Continue goes to Enable.
- Nothing installed: Plan install goes to Install.
- A different build: Plan update goes to Install, or Continue anyway uses the host as it is. A different build still connects, best effort, with a warning.
- SSH failed: fix what ssh reported, then Check again. If ssh couldn't resolve a bare name such as
you@studio, the dialog offers Try you@studio.local: on a local network a machine usually answers by its.localname.
3. Install
Install puts the exact build this machine runs onto the host, version and commit, so the two match. The plan says how it will get there before anything runs.
- A Mac host: when the host has the same architecture as this Mac, Daintree copies this Mac's own app across. Otherwise the host downloads the matching build from the Daintree release feed, or this machine downloads it and copies it over if the host can't reach the feed. It lands in
/Applications/Daintree.app, with the previous copy kept until the host is confirmed back. - A Linux host: a Package choice of AppImage or .deb. The AppImage is the default: it installs without root, to
~/Applications/Daintree.AppImage. Without FUSE on the host it still runs, unpacked each time it starts, which makes starting slower.
Every download is checked against the release feed's published checksum before it is used, and a downloaded Mac app must also pass the signature checks. Then Install on host (or Update host) runs it; Stop cancels it. Daintree stages and checks the new build on the host before it stops anything. Stopping a running Daintree ends its terminals; from there, the installer either finishes or tries to put the previous build back, and says whether it could.
.deb, so the dialog won't install one; choose the AppImage, or install the .deb on the host yourself and Check again. See AppImage or .deb.Updating a Host That Is Working
Updating a host where Daintree is running restarts it there, and that ends its terminals. Daintree says so first: Daintree is running there. Updating restarts it, which ends its terminals. If the host reports agents working, nothing changes until you choose:
- Update when idle waits until the host reports no working agents, then updates. It checks again right before stopping, in case work started meanwhile.
- Update now and end its terminals asks once more, Update 'studio-01' now?, because every terminal there ends and the agents in them stop mid-task.
After installing, Daintree reads the build back on the host, waits for Host mode to come back if it was on, and, for a host already in your list, reconnects to confirm the same build answers. A build that reads back wrong is rolled back. If the host doesn't answer the reconnect, the new build stays in place with the previous one kept beside it, and Daintree says so.
4. Enable
Enable turns on Host mode on the host and sets it to start at login, which is what makes the machine available to your windows.
- A Mac host: Daintree turns Host mode on in the logged-in session and sets it to start at login. If Daintree has never run on that Mac, open it once at the machine first: macOS asks to approve a first launch.
- A Linux host: Daintree installs its Host mode service (a systemd user unit), starts it if Daintree isn't already running there, turns Host mode on with start at login, and asks the host to keep the service running after you log out (linger). See The Service Daintree Installs.
Click Turn on Host mode, or Skip to leave the host as it is. If Host mode is already on and starts at login there, the step says Host mode is on at studio-01 and starts at login there. This machine can connect. and you just Continue.
When something fails here, the message names it. On Linux that includes the service's own first error, for example Daintree's Host mode service on you@server keeps exiting as it starts: …, so you rarely need to log in to find out why. Troubleshooting Remote Hosts lists the common ones.
5. Advise
The last step lists what Daintree observed about the host that affects how reliably it serves:
- Sleep: whether the host sleeps when idle. A sleeping host drops its connection.
- Keychain: whether plugins can store secrets there. Credentials aren't copied between machines; each host signs in for itself.
- Running after logout (Linux): whether the service keeps running with nobody logged in, and the host's own words if it refused linger.
- Local network (Macs): the macOS Local Network permission, on this Mac and on a Mac host. See Local Network Permission.
Where there is a fix, the step shows the command with Copy command: Keep this Mac awake (sudo pmset -a sleep 0 disksleep 0), Keep this machine awake on Linux, or Let Host mode run without a login session (loginctl enable-linger $USER). Daintree never runs sudo itself.
Add host saves it and, if the host is listening, connects. If the first connection fails, the host stays in the list (studio-01 was added to your hosts.) and you can Connect now or later from Settings → Hosts.
Manage Your Hosts
Settings → Hosts lists every host under Remote hosts: its name, its SSH target and platform, and its connection state, with Details and a Remove host button on each row. Below the list is This machine as a host, which controls whether this machine serves others; see This Machine as a Host.
Details opens the host's page:
| Section | What it holds |
|---|---|
| Connection | Name (what this device calls it), SSH target, Status with Connect or Retry (or Set up… when Host mode is off there), and Daintree build with Check for update. A connected host on a different build says Differs from this machine. |
| Notifications | Notify me about this host: agents observed waiting there notify you even while your windows show another machine. Off by default. |
| Agent CLIs | What the host reports having installed, with versions. Observe only: Daintree never installs agent CLIs on a host. |
| Accounts | The host's forge connections, such as Signed in as … on studio-01 or GitHub isn't connected on studio-01. |
| Plugins | This machine's plugins compared with the host's, with Install on studio-01 and Update on studio-01. See Plugins Across Machines. |
| Plugin views and Clipboard access | Your answers when a plugin from the host asked to run its view or use this computer's clipboard, each with Reset. |
| Remove host | Takes the host out of your list. |
Changing the SSH target clears what Daintree had recorded about the old one (platform, build, last seen) until it next connects.
Removing a Host
Remove host asks Remove 'studio-01' from this device? and then closes its connection here, returns any windows attached to it to this machine, and closes its ssh connection. Nothing on the host changes: its projects keep running, and Host mode and its start-at-login item stay as they were. To stop a machine from serving altogether, turn Host mode off on the machine itself.
Update a Host
Keeping every machine on the same release is the safe default. When you update this machine, update your hosts to match:
- Check for update on the host's details page opens the same dialog titled Update studio-01. Press Check host, then Plan update.
- When a host connects on a different build, Daintree shows one warning, Different build on studio-01, with an Update studio-01 button. If the host is the newer one, the button reads Update this machine instead.
- A host whose link protocol differs can't connect at all. Its row in the host menu reads Can't connect, and the menu offers the update.
On Linux you can also update by hand. See Updating a Linux Host.