When your phone can't connect

Start here. Everything on this page happens inside Obsidian, and none of it needs a terminal.

Run the check

On your computer, open Obsidian → Settings → Hyo → Mobile and click Run check next to “Check mobile access”.

It tests every part of the connection in turn and tells you which one failed and what to do about it:

• whether Tailscale is installed, and where it found it
• whether Tailscale is running and signed in
• whether Hyo’s gateway is listening
• whether your phone’s address has been published
• the address your phone will connect to

Most problems are named and solved right there.

If the status bar says “starting…” and stays there

Turn mobile access off, wait a moment, and turn it back on. If it sticks again, quit Obsidian completely and reopen it, then run the check.

If it still sticks, the log at ~/.hyo/mobile.log on your Mac (or C:\Users\<you>\.hyo\mobile.log on Windows) records every step of startup. The check tells you the path when something fails.

Let your agent fix it

If you’d rather not work through it yourself, paste this to your agent on the computer running Hyo. It has everything it needs to diagnose and repair the connection for you.

Hyo's mobile access won't start on this computer. Please diagnose and fix it.

How it works: the Hyo plugin runs a small WebSocket server on 127.0.0.1, then
asks Tailscale to publish it at a path named after the vault, so my phone can
reach it privately. The status bar shows "Mobile: on" when that has worked.

Please work through this in order and fix what you find:

1. Read ~/.hyo/mobile.log — the last startup attempt is at the bottom, and it
   records each step and any error.

2. Find the Tailscale CLI. On a Mac it is usually
   /Applications/Tailscale.app/Contents/MacOS/Tailscale, on Windows it is
   usually "C:\Program Files\Tailscale\tailscale.exe". Tell me where it is.

3. Check Tailscale is up: run `tailscale status --json` and confirm
   BackendState is "Running". If it says NeedsLogin or Stopped, tell me — I
   need to sign in myself.

4. Check the vault's address is published: run `tailscale serve status --json`.
   There should be a handler at /hyo-<vault-name-in-lowercase-with-dashes>
   proxying to http://127.0.0.1:<port>. Read the port Hyo is actually using
   from ~/.hyo/gateways/*.json.

5. If the handler is missing or points at the wrong port, republish it:
   `tailscale serve --bg --set-path=/<slug> <port>`
   using the slug and port from the previous step.

6. Confirm the port is really listening, then tell me the address my phone
   should be using: wss://<the DNSName from step 3>/<slug>

Explain what was wrong in plain language. Don't change anything in the vault.

If your phone still won’t connect

Check that Obsidian is open on your computer, that the computer’s status bar says 📱 Mobile: on, and that both devices show as connected in the Tailscale app. The server only runs while Obsidian is open.