Troubleshooting Remote Hosts
Fix Remote Hosts problems: testing SSH, common errors and what they mean, every connection state and where it shows, different builds, read-only terminals, hosts that restart themselves, and the logs and status files to check.
Test SSH First
Start with ssh, because it reports name, key and connection problems in its own words. Daintree runs ssh non-interactively, so run it the same way yourself, from the machine you work on:
ssh -o BatchMode=yes you@studio-01.local 'echo ok'If that prints ok, the basics work: name, key and login. Daintree also needs Host mode running on the host and ssh's socket forwarding (or its fallback), which the rest of this page covers. If it prints an error, compare it with ssh's lines quoted in the Check step and in the host's Status row in Settings → Hosts.
Common Problems
| What you see | What it means and what to do |
|---|---|
Could not resolve hostname studio | This machine can't find that name. On a local network use studio.local (the Check step offers Try you@studio.local); on Tailscale use the MagicDNS name; or add an alias to ~/.ssh/config. |
Permission denied (publickey…) | The host doesn't accept your key, or ssh wanted a password or passphrase. Run ssh-copy-id you@host, add your key to your ssh agent, and check that plain ssh you@host asks for nothing. |
Host key verification failed | The host key is new or changed. Connect once in a terminal and accept it, after confirming the change is expected. |
Connection refused or a timeout | No ssh server is answering. On a Mac, turn on Remote Login; on Linux, install and start openssh-server. Check that the host is awake and on the network. |
| Host mode reads Off, or Daintree isn't running in Host mode there | ssh works, but Daintree isn't serving. Use Set up… (or Turn on Host mode in the dialog). On Linux, check systemctl --user status daintree-host. |
| Couldn't start Daintree on … Log in there (or turn on automatic login), then connect again. | A Mac host serves only inside a logged-in session. Log in at the Mac, or turn on automatic login for that user. |
| Daintree's Host mode service on … keeps exiting as it starts: … | The Linux service crashed during setup; the message quotes its first error, such as a missing shared library. More is in journalctl --user -u daintree-host.service on the host. |
| The machine isn't under Machines found | Discovery lists only Tailscale peers and Bonjour adverts on port 22. Enter the SSH target by hand. |
| The Linux host stops when you log out | Check linger with loginctl show-user you -p Linger. If it says no, run sudo loginctl enable-linger you; if it says yes, check the service's status and journal. See Linger. |
| Couldn't reach this host. Check that it is on and try again. | A switch waited for the host and it didn't answer: 20 seconds normally, up to two minutes while Daintree was being started there. Check it is awake and reachable, then Retry. |
Connections to .local names fail on a Mac | Check Daintree's Local Network permission in System Settings → Privacy & Security → Local Network. If it is already on, check the name resolves and the host is up. |
| The release feed only publishes checksums for its current release… | A host can download only the current release. Update this machine first, or install Daintree on the host yourself. |
Connection States
The same state reads slightly differently on each surface. The window banner shows only in a window on that host.
| State | Window banner | Chip | Host menu and overview |
|---|---|---|---|
| Connecting | Connecting to studio-01… | connecting… | Connecting… |
| Lost, retrying | Connection to studio-01 lost. Reconnecting… | connecting… | Connecting… |
| Connected but silent | None | no reply | No reply, Last heard … |
| Unreachable | studio-01 is unreachable · last seen … with Retry | unreachable | Unreachable, Last seen … |
| Host mode off | As unreachable | unreachable | Host mode off |
| Refused build | studio-01 runs a different build | can't connect | Can't connect, Needs a compatible build |
| Disconnected by you | Disconnected from studio-01 with Connect | not connected | Not connected |
| Another machine has control | … has control of this project · Viewing here | viewing | Connected; the overview's Driving row names who drives |
A short blip shows no banner at all. During a long outage the banner alternates between unreachable and reconnecting as Daintree retries, backing off up to 30 seconds between attempts. Retry tries again at once. Settings → Hosts adds detail to the same states, including ssh's own error and the round-trip time.
Different Builds
When two machines connect, they exchange their build: version, commit and link protocol.
- Same build: nothing to see.
- A different version or commit connects anyway, best effort. Daintree shows one warning per host build, Different build on studio-01: Connected anyway: studio-01 runs a different build (0.43.0). Most things work; anything that changed between the two builds may not. Its button offers Update this machine when the host runs a newer version, and Update studio-01 otherwise, including when only the commit differs. The host's details page notes Differs from this machine beside its build.
- A different link protocol can't connect: neither side can read the other. The chip says can't connect and the host menu offers the update.
Keeping every machine on the same release avoids all of it. See Update a Host.
Terminals Won't Take Input
A terminal in a window on a host refuses typing in two situations, and says which:
- Read-only until studio-01 reconnects: the link is down. Output keeps coming once it is back; what you type isn't queued, so retype it.
- Read-only · Greg's MacBook Pro has control: another machine has control of the project. Click Take control. See Who Has Control.
Briefly after opening, a window also shows Read-only until studio-01 confirms who has control of this project, until the host answers.
A Host Starts Again After You Stop It
That is by design. When ssh reaches a set-up host whose Daintree isn't running, a client that needs it starts it the way it was set up: the Mac app in Host mode, or the Linux service. It never installs anything or turns Host mode on. To stop a host for good, turn Host mode off on it, remove it from the host list on the machines that use it, or on Linux disable the service and delete its unit file.
An Agent Isn't Available on the Host
The agent picker lists what the host has installed, and marks the rest Not installed on studio-01. Install the CLI on the host and sign in there, in a terminal on the host. Then use Re-check on the CLI pane. Daintree never installs agent CLIs on a host for you.
Logs and Status Files
- This machine: Settings → Hosts → the host shows the status with ssh's error, and the build on each side. For this machine's own log, see Diagnostics.
- The host: Settings → Hosts → This machine as a host, at the host, shows its socket, start at login, keychain, sleep and attached machines.
- A Linux host:
journalctl --user -u daintree-host -efor the service log, andsystemctl --user status daintree-host. - Status files on the host:
host.jsonis written when Daintree starts listening and removed when it stops cleanly (after a crash it can be left behind, and Daintree checks that the process it names is alive);host-mode.jsonrecords the last known Host mode setting, start at login, the build and the keychain check. On macOS they are in~/Library/Application Support/Daintree/; on Linux in/run/user/<uid>/daintree/.
-e, or follow new lines with -f.