Skip to content
Muxen
Docs · Troubleshooting

More

Troubleshooting

What each “can’t connect” message means and how to fix it, plus where Muxen keeps its files and how to get help.

When Muxen can’t reach a machine, its card and its page say why in a few words, and usually what to do. Here’s each message, what causes it, and the fix. When a message comes with a command (a hint), run it in a terminal on this computer: it’s the quickest way to see or fix what ssh is complaining about.

An offline machine's page: Harbor is offline, shut down, asleep, or off the network, with Wake and Try again. An offline machine's page: Harbor is offline, shut down, asleep, or off the network, with Wake and Try again.
Every machine that can’t be reached says why, with what you can do about it.

“Can’t connect” messages

“X is offline”

It didn’t answer at all: shut down, asleep, or off the network. Nothing’s wrong on your end, and Muxen reconnects when it’s back. Its page says when it was last seen. If Muxen knows its network card, Wake sends a Wake on LAN signal. With Tailscale, “Tailscale doesn’t see it either” confirms it’s really off.

“X isn’t accepting connections”

The machine is there, but nothing answers on the ssh port. Either it’s still starting up, or its ssh server is off:

  • Mac: turn on Remote Login in System Settings › General › Sharing.
  • Windows: OpenSSH Server isn’t running. See Windows to set it up and start it.
  • Linux: start its ssh server, for example sudo systemctl enable --now ssh (sshd on some systems).

“X doesn’t know this Mac yet”

ssh reached it, but your key wasn’t accepted. Set up access once, with your password there; the hint has the command:

ssh-copy-id -i ~/.ssh/id_ed25519.pub user@host

Then Try again. On a Windows PC with an administrator account, the key goes in a different file; see Windows.

“Can’t find X”

Its name doesn’t resolve to an address. Check the host in its settings or your ssh config for a typo, or join the network or VPN it’s on.

“X’s ssh identity changed”

The machine’s host key isn’t the one ssh remembers. That’s expected after reinstalling it. Remove its old key and connect once to accept the new one:

ssh-keygen -R host
ssh user@host

If you didn’t reinstall it or change its address, find out why before accepting the new key: ssh warns about this because it can also mean something is pretending to be your machine.

“Tailscale is off on this Mac”

The machine is reached through Tailscale, and Tailscale is off or signed out on this computer. Turn it on, or sign in, and Muxen reconnects. Muxen never changes Tailscale’s settings itself.

A related one: “X is on, but not answering”. Tailscale sees the machine, so it’s on; its ssh may be off, or a firewall is in the way.

“X didn’t finish the check”

It answered, but the check took too long: the machine is very busy, or the connection is poor. Try ssh in a terminal to see how it responds.

“Beacon is offline” on another machine

A machine reached through another one (a VM, or one behind a jump host) can’t be reached when the one in front is off. The message names that machine: wake or start it first. “X isn’t answering” means the machine in front is up, but nothing answers behind it.

A VM: “stopped” or “installing”

  • “X is stopped”: its container on the host isn’t running. Start it from its page or right-click menu.
  • “Installing Windows 11…”: Windows is still installing itself, 15 to 30 minutes the first time. Watch the install on its page shows its screen.
  • “X is powered off”: a cloud machine you powered off. It’s still billed. See Cloud machines.

Direct connections on a Mac: Local Network

macOS asks before an app talks to devices on your local network. If you said no, or the prompt never came, direct connections to machines at home fail and Muxen uses ssh instead. The Connection card says “Not reachable on this network”.

  1. Open System Settings › Privacy & Security › Local Network.
  2. Turn on Muxen.
  3. Quit Muxen and open it again.

When the machine you’re connecting to is a Mac, allow muxen-agent in the same place on that Mac. If neither is the problem, UDP port 47821 is probably blocked between you. See Direct connections.

Password prompts

A few things need root on the machine: starting or stopping a system service, ending another user’s process, adding a virtual monitor on Linux. When sudo there wants a password, the app asks you for it, passes it to sudo over its encrypted connection, and keeps it in memory only until you quit. Nothing is saved.

The command line and MCP can’t ask, so they fail with a hint to do it in the app instead. For runners on Linux, passwordless sudo lets Muxen install them as services; without it, they run in Docker or in the background.

Where Muxen keeps its files

  • config.toml: your machines and settings, in ~/.config/muxin/ (%APPDATA%\muxin\ on Windows), or $MUXIN_HOME if that’s set. You can edit it by hand; Muxen keeps your comments.
  • state.json, beside it: the last machine check, and what Tailscale last said about each machine.
  • direct.json, beside it: the machines paired for direct connections.

muxen paths prints where they are.

Getting help

Still stuck? Write to contact@lumarylabs.com. Say what the machine is (Mac, Linux, Windows, a VM), the message Muxen shows, and what ssh says when you connect from a terminal.