Troubleshooting

The Screen Is Black

A black remote desktop almost always means a missing permission on the host (the machine being controlled). See Permissions for the full list.

Quick checklist:

• macOS: grant Screen Recording permission and restart the Wihaister service
• Windows: confirm the tunnel service is running — its icon should be visible in the system tray
• Both machines online and connected to the same Wihaister network

The Camera Feed Is Missing

Camera streaming requires camera access on the workstation:

1. Open System Settings → Privacy & Security → Camera (macOS).
2. Enable Wihaister and restart the service.

Also make sure another application is not already using the camera exclusively — most cameras can only be opened by one application at a time.

Connection Code Problems

Connection codes are single-use and valid for 48 hours from the moment they are generated.

• If a code is rejected, generate a new one on the host and try again — the old code cannot be reused
• Enter the code exactly as shown, including the dashes (format: XXXX-XXXX-XXXX)
• Codes expire automatically after 48 hours even if they were never used

Connection Is Slow

Wihaister adjusts stream quality to match your network conditions automatically. If the picture feels sluggish:

• Move closer to your Wi-Fi access point or use a wired connection
• Close bandwidth-heavy applications on both machines
• Keep in mind that both endpoints matter: the slowest hop in the path limits the whole session
• Sessions that run through the relay fallback have higher latency than direct connections

Why Is My Session Using a Relay

Wihaister always tries to establish a direct peer-to-peer connection between your devices, punching through NATs and firewalls automatically. In some network environments a direct path simply cannot be established — restrictive firewalls or carrier-grade NAT are common causes.

When that happens, the session falls back to a relay server for as long as needed. Your traffic is still end-to-end encrypted: the relay only forwards encrypted bytes and cannot read your data. Functionally, relayed sessions behave the same as direct ones; they may have slightly higher latency.

There is no way to see from inside the product whether a session is direct or relayed — the connection behaves identically either way.

Connection Drops

• Confirm both machines are online and Wihaister is running on both
• The client reconnects automatically — wait a moment before retrying manually
• Re-enter the connection code if the session cannot be resumed; codes are single-use, so share a fresh one from the host
• If the tunnel service appears unresponsive, restart it on the host and reconnect

Collecting Diagnostics

If you need help from the team, gathering a few details first speeds things up:

• Which platforms both machines run (and their OS versions)
• What you were doing when the problem appeared
• Whether the problem happens on every connection or only specific networks
• The exact wording of any error message

For advanced diagnostics, the desktop client can be started with verbose logging by setting the RUST_LOG environment variable to debug before launching it from a terminal.

Still Stuck

Wihaister is in early access. If you cannot resolve an issue with the steps above, reach out through the channel in your early access invitation — including the diagnostics from the section above.